This is the README for eni.a.tar.gz [Download] [Browse] [Up]
Eni - an Ethernet Interface
---------------------------
Eni (EtherNet Interface) is a library of routines providing low level access
to the Ethernet. Currently it is available only on the NeXT computers. It
has two parts: the programmer's interface, consisting of a library linked to
the user's program, and a loadable kernel module, which is an intermediary
between the library and the actual Ethernet device driver.
Programmer's Interface:
The interface routines are contained in a library: /usr/local/lib/eni.o on
the NeXTs. It can be linked with a user program with a command similar to
the following:
cc -I/usr/local/include -o foo foo.c /usr/local/lib/eni.o
(Some sample programs are contained in /usr/local/eni/lib. See the section
"Examples" for more details on running them.)
This library currently provides three routines:
- "eni_init" which should be called once by the program communicating
over the network. It must be the first "eni" routine
called.
- "eni_get_packet" which blocks, waiting for an Ethernet packet to arrive.
Upon return, it places the received packet into a buffer
provided by the user.
- "eni_send_packet" hands a packet to the kernel to be sent over the
Ethernet. It provides a slight convenience, in that
the user needn't completely assemble the packet, but
can seperately supply the destination address, frame
type and data.
These routines are descibed in detail in separate man pages.
To use the routines in this library it is recommended you include the file
"libeni.h" in your programs. It includes values which you need, and others
that you may find useful. This file resides in the directory
/usr/local/include, which is not in the standard search path for include
files. Therefore, you must give the -I option to the C compiler, as in the
example above.
Among other things, this include file defines the following values:
ADDR_SIZE - the number of bytes in an Ethernet address
TYPE_SIZE - the number of bytes used by the Ethernet frame type
DADDR_OFFSET - the offset into an Ethernet packet, in bytes, of the
destination address
SADDR_OFFSET - offset of the source address
TYPE_OFFSET - address of the frame type
DATA_OFFSET - offset of the first byte of data
ENI_MTU - the maximum number of bytes in the data portion of
the packet
ENI_PACKET_SIZE - the maximum size of our packet, including headers
ENI_MTU is an upper bound on the amount of data you can put in a packet (to
pass to eni_send_packet), and any buffer you pass to eni_get_packet should
be at least ENI_PACKET_SIZE bytes in length.
Loadable Kernel Server:
The other half of "eni" is a set of routines which is loaded into the kernel
at run time. They must be present for the library routines to work
properly. The kernel server is contained in the file /usr/local/lib/eni, and
can be loaded with the command:
/usr/local/bin/load_eni
No harm will be done if this is run while "eni" is already loaded; it will
merely print a few complaints.
This module is necessary because we must communicate with the actual Ethernet
device driver to output packets. Doing this requires access to routines
defined only within the kernel. In turn, the "eni" library communicates with
the kernel server via the Mach message passing mechanism.
Utility Routines:
There are some utility routines contained in the file
/usr/local/lib/eniutil.o, among which two may be of use: hex_to_addr and
addr_to_hex. They convert between an hexadecimal (string)
representation of Ethernet addresses and the "binary" (six byte)
format. They are described in a man page and are used in the sample
program enitest.c.
Examples:
There are a few sample programs contained in the directory
/usr/local/eni/examples. Included is a makefile for compiling them. To
run any of these programs you should make a subdirectory under your home
directory, and copy the relevant files to it. For example:
% cd
% mkdir eni
% cd eni
% cp /usr/local/eni/examples/* .
At this point you can make the executables with a command similar to the
following:
% make enitest
The command:
% make all
will compile all the sample programs.
Remember, for these to work "eni" must have been loaded with 'load_eni'.
Caveats:
Currently, "eni" has certain characteristics which might cause problems
for the unsuspecting user.
- only one task (process) may use these routines at a time. That is, you
cannot have two programs, running on the same machine, which both call
"eni_init" (or use any of the other routines) running at the same time
(well, you can, but it won't work properly). This is not too serious
a limitation, as Mach (the NeXT operating system) allows multiple
threads to run within a single task. All threads within a task have
the same memory map -- basically giving them all access to the same
global variables. The 'cthreads' library of routines (part of the
standard NeXT library) provides relatively high level access to
threads. Routines to perform locking, provide for critical sections
and concurrent access to global data structures are also available.
The sample program enitest.c makes use of some 'cthreads' routines.
- the Ethernet packets produced by "eni" will not be transmitted through
gateways. This means that only bart, homer, quiche and the second
floor NeXTs will receive them (as these machines are on the same
subnet). The non-NeXT machines can be ignored since this software
does not run on them.
- the packets you pass to the "eni" routines are not quite the same as
"standard" Ethernet packets, in that the amount of data they can hold
is smaller by two bytes. Hence the definitions of ENI_PACKET_SIZE and
ENI_MTU.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.