Subversion Repositories Kolibri OS

What is implemented

===================

The following features are present in the TCP/IP stack code:

  IP layer.

  ICMP.

  TCP layer.

  UDP layer.

  local loopback.

  Realtek 8029 PCI ethernet interface.

  Realtek 8139 PCI ethernet interface.

  Intel i8255x PCI ethernet interface.

  Dynamic ARP table.

  PPP dialer

And the following internet applcations are implemented

  HTTP Server

  Telnet

  POP Client

  DNS Name resolver

  MP3 Server

  TFTP Client

  IRC Client

There are also a number of experimental applications for streaming music

and performing interprocess communication via sockets. A Web broswer is in

development

What is not implemented

=======================

The IP layer does not process header options.

The IP layer does not support routing.

Packet fragmentation is not supported.

How to configure Kolibri for PPP

===============================

See ppp.txt

How to configure Kolibri for Ethernet

====================================

First, you need to have a supported ethernet card fitted, or present

on your motherboard. If you are uncertain what type of hardware you

have, try to configue the stack. If you have supported hardware it

will be found, and enabled.

Setting Up the ARP Table

------------------------

Kolibri's ARP table is dynamically created and maintained; You can see what

hosts Kolibri has communicated with by running the ARPSTAT application.

Enabling Ethernet

-----------------

Boot Kolibri, then select STACKCFG from the NET menu.

Press the 'Read' Button, then select 'Packet Driver'.

Press 'Change' next to the IP address, and enter the IP address you want

to use. Make sure it is on the same sub-net as the LAN to which you are

connected.

Press 'Apply' to action the changes.

Close the program.

The stack is now running, which you can test by pinging Kolibri from a

remote host.

The simplest way to connect two PC's together is using a 'Null Modem'

Ethernet cable. These simply cross certain wires over. They can be

purchased from PC stores, but are simple to make. Details can be found

on the web. Look on google for 'ethernet cross over cable' or similar.

How to use TCP/IP locally, with no Network

==========================================

Kolibri supports a form of local loopback that means applications on the

same PC can communicate with each other via sockets as though they

were on separate hosts. To connect to an application on the same machine,

specify the local IP address as the destination address. You do not even

need to configure the stack for ethernet; local loopback will work without

any network hardware. It's great for development and testing.

Application Programming Interface

=================================

The developer can access the stack through interrupt 0x40, function 53.

The file TFTPC.ASM gives a good example of how to use the programming

interface ( at least, for UDP), but as network communication is complex

I'll give an overview.

Sockets

=======

Applications connect to each other and pass information between themselves

through a mechanism called a 'socket'. Sockets are end-points for

communication; You need one at each application to communicate.

Using sockets is a little like using files on an OS; You open them, read

and write to them, then close them. The only thing that makes life slightly

more complicated is that unlike with a file, you have something intelligent

at the other end ( which for example may not want to close when you do! )

Lets deal with the terminology before we go any further.

socket      A unique identifier used by the application for communication.

local port  A number that identifies this application on the local host.

            Ports are a way to allow multiple applications to communicate

            with other hosts without the data becoming mixed up. ( The

            technical term is 'multiplex' ). Port numbers are 16 bit.

remote port A number that identifies the application on the remote host

            to which we are communicating with. To the remote host, this is

            it's 'local port'. Port numbers are 16 bit.

IP Address  A 32 bit number that identifies the remote host PC that we are

            communicating with.

Passive     Refers to the mode by which a socket is opened; When opening in

            passive mode, the local PC is awaiting an incoming connection.

Active      Refers to the mode by which a socket is opened; When opening in

            active mode, the local PC will attempt to connect to a remote

            PC.

When you connect to a socket on a remote PC, you need to specify more than

just the IP address, otherwise the remote stack will not know to which

application it should send your data. You must fully qualify the address,

which means you specify the IP address and the port number. This would be

written like this

192.168.1.10:80   ; Connect to port 80 on the machine 192.168.1.10

Port numbers are important. Some are 'well known' and provide access to

common applications. For example port 80 is used by HTTP servers; That

way I can connect to a webserver on a host without having to find out

what port number the application is listening on.

This brings me to the way in which you open a socket; As I said earlier,

there are two modes, Passive and Active. A webserver would open a passive

socket, as it is waiting for incoming connection requests. A web browser

would open an active socket because it is attempting to connect to a

specified remote host.

Access to programming interface

===============================

The developer accesses the stack functions through interrupt 0x40,

function 53. Some functions may be accessed through function 52, but these

are mainly for stack configuration.

Here is a summary of the functions that you may use and the parameter

definitions.

Get Local IP Address

--------------------

eax = 52

ebx = 1

IP address returned in eax ( in internet byte order )

Write to stack input queue

--------------------------

eax = 52

ebx = 6

edx = number of bytes to write

esi = pointer to data ( in application space )

On return, eax holds 0 for OK, or 0xFFFFFFFF for error.

This interface is for slow network drivers only ( PPP, SLIP )

Read data from network output queue

-----------------------------------

eax = 52

ebx = 8

esi = pointer to data ( in application space )

On return, eax holds number of bytes transferred.

This interface is for slow network drivers only ( PPP, SLIP )

Open a UDP socket

-----------------

eax = 53

ebx = 0

ecx = local port

edx = remote port

esi = remote ip address ( in internet byte order )

The socket number allocated is returned in eax.

A return value of 0xFFFFFFFF means no socket could be opened.

Open a TCP socket

-----------------

eax = 53

ebx = 5

ecx = local port

edx = remote port

esi = remote ip address ( in internet byte order )

edi = mode : SOCKET_PASSIVE or SOCKET_ACTIVE  ( defined in stack.inc )

The socket number allocated is returned in eax.

A return value of 0xFFFFFFFF means no socket could be opened.

Close a socket (UDP Only )

--------------------------

eax = 53

ebx = 1

ecx = socket number

On return, eax holds 0 for OK, or 0xFFFFFFFF for error.

Close a socket (TCP Only )

--------------------------

eax = 53

ebx = 8

ecx = socket number

On return, eax holds 0 for OK, or 0xFFFFFFFF for error.

Poll socket

-----------

eax = 53

ebx = 2

ecx = socket number

On return, eax holds the number of bytes in the receive buffer.

Read socket data

----------------

eax = 53

ebx = 3

ecx = socket number

On return, eax holds the number of bytes remaining, bl holds a data byte.

Write to socket ( UDP only )

----------------------------

eax = 53

ebx = 4

ecx = socket number

edx = number of bytes to write

esi = pointer to data ( in application space )

On return, eax holds 0 for OK, or 0xFFFFFFFF for error.

Return socket status ( TCP only )

---------------------------------

eax = 53

ebx = 6

ecx = socket number

On return, eax holds the sockets TCP status.

This function can be used to determine when a socket has actually connected

to another socket - data cannot be written to a socket until the connection

is established (TCB_ESTABLISHED). The states a socket can be in are defined

in stack.inc as TCB_

Write to socket ( TCP only )

----------------------------

eax = 53

ebx = 7

ecx = socket number

edx = number of bytes to write

esi = pointer to data ( in application space )

On return, eax holds 0 for OK, or 0xFFFFFFFF for error.

Check port number

-----------------

eax = 53

ebx = 9

ecx = port number

This function is used to determine if a port number

is in use by any sockets as a local port number. Local

port numbers are normally unique.

On return, eax is 1 for port number not in use, 0 otherwise.

Opening a TCP socket in Kolibri

===============================

There are two ways to open a socket - Passive or Active.

In a Passive connection your application 'listens' for incoming

requests from remote applications. Typically this will be done when

you are implementing a server application that allows any other

application to connect to it. You would specify a 'known' local

port number, such as 80 for a web server. You would leave the

remote IP and remote port number as 0, which indicates any

remote application may connect.

Once the socket has been opened you would wait for an incoming

connection before doing anything. This can be by either checking

the socket status for TCB_ESTABLISHED, or waiting for data in the

receive buffer.

In an Active connection, you are making a connection to a specified

remote port. The remote IP and remote port parameters must be filled

in with non-zero values ( otherwise, what are you connecting to? ).

You also specify a unique local port number so the remote application

can uniquely identify you - after all, there may be several applications

on your machine connected to the same remote host. See below for finding

a unique port number.

How to find an unused local port number

=======================================

Typically when you are creating an active connection to a remote

socket you will want to choose a unique local port number. Local

port numbers normally start from 1000; The following code may

be used to obtain an unused port number prior to making the

open socket call.

    mov     ecx, 1000        ; local port starting at 1000

getlp:

    inc     ecx

    push    ecx

    mov     eax, 53

    mov     ebx, 9

    int     0x40

    pop     ecx

    cmp     eax, 0            ; is this local port in use?

    jz      getlp            ; yes - so try next

    ; ecx contains a free local port number

Writing data to a socket

========================

There are two functions available depending on whether the socket

was opened for TCP or UDP protocol; The call parameters are the

same however. When the socket is being opened for TCP, use the

status function to poll for a connection - data cannot be written

to a socket until another socket has connected to it, and the

state of the socket is TCB_ESTABLISHED.

When you write data, the call results in a single IP packet being

created and transmitted. Thus the user application is responsible for

the size of transmitted packets. Keep the packet sizes under 768 bytes.

If you are writing a terminal program like telnet, you may want to send

a packet for each keystroke ( inefficient ) or use a timer to send data

periodically ( say, every second ).

Reading data from a socket

==========================

There is one function to read data from a sockets receive buffer. This

function retrieves one byte at a time. You can use the poll function to

test the receive buffer for data.

Closing a socket

================

Simply call the appropriate function - there is one for TCP, and another

for UDP. When closing a TCP socket, don't forget that the other end

may continue to send data, so the socket may remain active for a

few seconds after your call.

If you have any questions or have suggestions for improving this

document please contact me at mikeh@oceanfree.net.