DATA STRUCTURES


struct fbuffer
{
  int len;
  int ifnum;
  int ofnum;
  char frame[1];
};

An fbuffer is a structure which stores a frame and information about it.  An
fbuffer should never be declared explicitly.  Instead, a pointer to an fbuffer
should be set to point to a block of memory sufficiently large to hold a
maximum sized frame plus the additional information stored in the fbuffer (the
incoming interface and the length of the frame) plus any alignment offsets.
Examples : 

  struct fbuffer *fb; 
  int buffer[2048];

  fb = (struct fbuffer *)buffer;
  fb = malloc(1500 + sizeof(int) * 2);

Dynamically allocated fbuffers must be disposed of by the programmer.  None of 
the API functions attempt to deallocate the memory pointed to by a fbuffer 
pointer.

The len field is set to the total length of the frame.

The ifnum field is set to the number of the interface on which the frame was
recieved.  

The ofnum field is set to the number of the interface on which the frame will
be sent.  (by framesend())

The frame field is a handle to the memory containing the actual packet data
including frame header.




FUNCTIONS


int npstart(char *addr, char *iname);

The npstart() function is used to initialize a connection to a network
processor.  None of the other functions in this API will operate properly if a 
session has not first been initialized by npstart().  The argument addr, gives
the hostname or ip address of the network processor.  If the program calling
this function is being run on the network processor itself, a NULL can be
passed as the argument insteand.  The iname argument gives the block name of
the interface ACE running on this system.  ("ifaceInput" is the usual, but it
is configured in the ixsys.config file) npstart() returns 0 on successful 
completion and -1 on an error.



int framesend(struct fbuffer *buf, int safill);

The framesend() function sends a frame stored in an fbuffer out the interface 
specified by the ofnum field of the first argument.  If the safill parameter is 
set to a non-zero value, then the source address of the frame will be filled in 
with the source address of the outgoing interface.  This function returns a 0 on
success.  It returns a -1 if there was an error sending the packet to the port, 
or a -2 if there was an error reading the response.



int framerecv(int ifnum, struct fbuffer *fbuf);

The framerecv() function waits until a frame arrives on the interface specified
by the first argument.  When a frame arrives, framerecv copies it into the
location pointed to by the second argument.  (see earlier rules regarding 
fbuffer memory allocation).  framerecv() sets the ifnum and len fields in the 
fbuffer.  The function returns a 0 on success, a -1 if there was an error 
contacting the network processor, and a negative -2 to -4 if there was an error 
getting the response.



int nextframe(struct fbuffer *fbuf);

The nextframe() function waits until a frame arrives on any interface.  It then
copies the frame into the memory pointed to by the argument.  nextframe() sets 
the ifnum and len fields of the fbuffer structure appropriately.  nextframe() 
returns 0 on success, -1 if there was an error contacting the network processor
and -2 to -4 if there was an error reading its response. 



int ifready(int ifnum, int direction);

The ifready() function checks whether the interface specified by the first
argument is ready to be read from or written to depending on the direction 
specified in the second argument.  If direction is set to INGRESS, ifready() 
checks if any packets have come in on the speicified interface and are
available to be read.  If direction is set to EGRESS then ifready() checks 
whether the network processor can send a frame to the specified interface.  
INGRESS and EGRESS are defined in npapi.h.  ifready() returns a 0 if an 
interface is not ready to perform the specified operation.  It returns a 
positive value if the interface is ready.  It returns a -1 if the direction 
argument is not set to INGRESS or EGRESS, -2 if there is an error contacting 
the network processor and -3 to -4 if there is an error getting its response. 

If an ifready(n, INGRESS) returns a positive number then the next call to 
nextframe() or framerecv() on interface n will not have to wait for a packet.



int npstop(void);

The npstop() function breaks the connection between a program and a network
processor started by npstart().  It returns 0 on a success and a -1 on a
failure.  After running npstop(), framesend(), framerecv(), nextframe() and 
ifready() will return errors unless npstart() is called first.
