home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-2.iso / Developer / resources / libraries / eni.README < prev    next >
Encoding:
Text File  |  1991-09-24  |  6.1 KB  |  148 lines
  1.                         Eni - an Ethernet Interface
  2.                         ---------------------------
  3.  
  4. Eni (EtherNet Interface) is a library of routines providing low level access
  5. to the Ethernet. Currently it is available only on the NeXT computers.  It
  6. has two parts: the programmer's interface, consisting of a library linked to
  7. the user's program, and a loadable kernel module, which is an intermediary
  8. between the library and the actual Ethernet device driver.
  9.  
  10. Programmer's Interface:
  11.  
  12. The interface routines are contained in a library: /usr/local/lib/eni.o on
  13. the NeXTs.  It can be linked with a user program with a command similar to
  14. the following:
  15.  
  16.     cc -I/usr/local/include -o foo foo.c /usr/local/lib/eni.o
  17.  
  18. (Some sample programs are contained in /usr/local/eni/lib.  See the section
  19. "Examples" for more details on running them.)
  20.  
  21. This library currently provides three routines:
  22.  
  23.     - "eni_init" which should be called once by the program communicating
  24.                  over the network.  It must be the first "eni" routine
  25.                  called.
  26.  
  27.     - "eni_get_packet" which blocks, waiting for an Ethernet packet to arrive.
  28.                        Upon return, it places the received packet into a buffer
  29.                        provided by the user.
  30.  
  31.     - "eni_send_packet" hands a packet to the kernel to be sent over the
  32.                         Ethernet.  It provides a slight convenience, in that
  33.                         the user needn't completely assemble the packet, but
  34.                         can seperately supply the destination address, frame
  35.                         type and data.
  36.  
  37. These routines are descibed in detail in separate man pages.
  38.  
  39. To use the routines in this library it is recommended you include the file
  40. "libeni.h" in your programs.  It includes values which you need, and others
  41. that you may find useful.  This file resides in the directory
  42. /usr/local/include, which is not in the standard search path for include
  43. files.  Therefore, you must give the -I option to the C compiler, as in the
  44. example above.
  45.  
  46. Among other things, this include file defines the following values:
  47.  
  48.     ADDR_SIZE   - the number of bytes in an Ethernet address
  49.     TYPE_SIZE   - the number of bytes used by the Ethernet frame type
  50.  
  51.     DADDR_OFFSET    - the offset into an Ethernet packet, in bytes, of the
  52.                       destination address
  53.     SADDR_OFFSET    - offset of the source address
  54.     TYPE_OFFSET     - address of the frame type
  55.     DATA_OFFSET     - offset of the first byte of data
  56.  
  57.     ENI_MTU            - the maximum number of bytes in the data portion of
  58.                          the packet
  59.     ENI_PACKET_SIZE    - the maximum size of our packet, including headers
  60.  
  61. ENI_MTU is an upper bound on the amount of data you can put in a packet (to
  62. pass to eni_send_packet), and any buffer you pass to eni_get_packet should
  63. be at least ENI_PACKET_SIZE bytes in length.
  64.  
  65.  
  66. Loadable Kernel Server:
  67.  
  68. The other half of "eni" is a set of routines which is loaded into the kernel
  69. at run time.  They must be present for the library routines to work
  70. properly.  The kernel server is contained in the file /usr/local/lib/eni, and
  71. can be loaded with the command:
  72.  
  73.     /usr/local/bin/load_eni
  74.  
  75. No harm will be done if this is run while "eni" is already loaded; it will
  76. merely print a few complaints.
  77.  
  78. This module is necessary because we must communicate with the actual Ethernet
  79. device driver to output packets.  Doing this requires access to routines
  80. defined only within the kernel.  In turn, the "eni" library communicates with
  81. the kernel server via the Mach message passing mechanism.
  82.  
  83.  
  84. Utility Routines:
  85.  
  86.     There are some utility routines contained in the file
  87.     /usr/local/lib/eniutil.o, among which two may be of use: hex_to_addr and
  88.     addr_to_hex.  They convert between an hexadecimal (string)
  89.     representation of Ethernet addresses and the "binary" (six byte)
  90.     format.  They are described in a man page and are used in the sample
  91.     program enitest.c.
  92.  
  93.  
  94. Examples:
  95.  
  96.     There are a few sample programs contained in the directory
  97.     /usr/local/eni/examples.  Included is a makefile for compiling them.  To
  98.     run any of these programs you should make a subdirectory under your home
  99.     directory, and copy the relevant files to it.  For example:
  100.  
  101.         % cd
  102.     % mkdir eni
  103.     % cd eni
  104.     % cp /usr/local/eni/examples/* .
  105.  
  106.     At this point you can make the executables with a command similar to the
  107.     following:
  108.  
  109.         % make enitest
  110.  
  111.     The command:
  112.  
  113.         % make all
  114.  
  115.     will compile all the sample programs.
  116.  
  117.     Remember, for these to work "eni" must have been loaded with 'load_eni'.
  118.  
  119.  
  120. Caveats:
  121.  
  122.     Currently, "eni" has certain characteristics which might cause problems
  123.     for the unsuspecting user.
  124.  
  125.     - only one task (process) may use these routines at a time.  That is, you
  126.       cannot have two programs, running on the same machine, which both call
  127.       "eni_init" (or use any of the other routines) running at the same time
  128.       (well, you can, but it won't work properly).  This is not too serious
  129.       a limitation, as Mach (the NeXT operating system) allows multiple
  130.       threads to run within a single task.  All threads within a task have
  131.       the same memory map -- basically giving them all access to the same
  132.       global variables.  The 'cthreads' library of routines (part of the
  133.       standard NeXT library) provides relatively high level access to
  134.       threads.  Routines to perform locking, provide for critical sections
  135.       and concurrent access to global data structures are also available.
  136.       The sample program enitest.c makes use of some 'cthreads' routines.
  137.  
  138.     - the Ethernet packets produced by "eni" will not be transmitted through
  139.       gateways.  This means that only bart, homer, quiche and the second
  140.       floor NeXTs will receive them (as these machines are on the same
  141.       subnet).  The non-NeXT machines can be ignored since this software
  142.       does not run on them.
  143.  
  144.     - the packets you pass to the "eni" routines are not quite the same as
  145.       "standard" Ethernet packets, in that the amount of data they can hold
  146.       is smaller by two bytes.  Hence the definitions of ENI_PACKET_SIZE and
  147.       ENI_MTU.
  148.