[Sois-tcons] Proposed TCONS API manpage

[gregory.menke at gsfc.nasa.gov]

Hi all, I spent some time on the plane working up the API a bit more.
The file follows.  I think it is not entirely right yet, but its
getting there.  If you have comments, flames, etc.. please respond w/
them and I'll update accordingly.  It seems like a coherent,
implementable API might be a concrete & welcome result from the CSA
meetings.

Greg



===File /home/posixfsw/gregm/gpmeth/docs/tcons-api.text=====

Issues;

- Restored the per-packet priority concept.  Rationale; If an
  application of TCONS runs without a schedule table, then there is no
  other way to prioritize traffic.  I think a caveat in the docs that
  the user must accept the consequences of varying packet priority is
  adequate.

- Some aspects of how qos plays out in the api are still obscure.

- The "connection" vs "connection-less" terminology is a bit clumsy.

- I don't accurately understand/recall how connectionless traffic is
  mapped to a channel.  My default thought is that all connectionless
  traffic is mapped to a single, predefined channel.  However, the CSA
  meetings were starting to make me think that since the SAP pair
  defines both ends of a stream of packets, we were half-way to making
  each unique pair of src & dest saps its own channel.  I don't think we
  want to go that far, I think all connectionless traffic mapped to a
  single channel is probably the way to go.


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


TCONS manpage;




connectionid_t make_connectionless_channel( sap_t src_SAP, sap_t dest_SAP )

   Creates a connectionless channel identifier between two endpoints but
   does not attempt to allocate an end-to-end connection.  This function
   compiles enough endpoint information to allow the transfer data units
   from the src_SAP to the dest_SAP.  The dest_SAP must be fully
   specified, the src_SAP may be completely specified or may employ a
   wildcard for the address and/or port elements.  Connectionless
   transfers do not honor all qos parameters, if unsupported parameters
   are requested, TCONS will ignore them.





qos_t	make_qos_descriptor(void)

   Creates a qos descriptor of default properties.  A default quality of
   service specifies low priority, unguaranteed transfer.


void set_qos_priority( qos_t *qos, int priority )

   Encodes the the given priority into the qos.  The last priority set
   takes effect.  TCONS transmit queues are ordered by priority.
   Adjusting a qos priority allows the sending application to affecting
   the sending order of packets queued for transmit.  If the sender
   varies priority, the receiving application must be prepared to accept
   data units in an different order than the sender submitted them to
   TCONS.  Priority always operates on a per-channel basis, not globally
   for all outgoing data-unit streams from a given host.  Global
   priority management for all of a host's outgoing traffic is achieved
   by using connectionless channels exclusively (all connectionless
   traffic is considered a single channel with respect to qos) or by
   using connections and supplying a transmit schedule table.


void set_qos_guaranteed( qos_t *qos, int enable )

   enable turns on or off the guaranteed flag in the given qos; !=0 to
   enable, 0 to disable.  Guaranteed qos is supplied at the datalink
   level, via the datalink's timeout/retry algorithm and subject to
   the subnetwork's schedule table.  The application must anticipate
   the delay product incurred from acks, timeouts and retries and
   queuing delays accumulated over each subnetwork hop.  The delay
   product will vary with network load among other factors, but may be
   constrained by using connections and configuring schedule tables.
   If schedule tables and connections are not used, the delay product
   is unconstrained out to sum of the worst case retry/timeout delays
   of all subnetworks the data-unit must transit.  Configuration of
   schedule tables with specific bandwidth and deadline parameters is
   a system engineering issue that is outside the scope of this api.
   TCONS does not make dynamic configuration or reconfiguration of
   schedule tables part of the standard api, however implementations
   are free to set up any table management procedures they choose.


void delete_qos_descriptor( qos_t qos )

   Releases any resources associated with a given qos created by
   make_qos_descriptor().  A qos descriptor is never bound to a
   connection and may be deleted at any time.  A TCONS implementation
   may or may not allocate resources when a qos descriptor is created,
   however an application must assume it does and call
   delete_qos_descriptor() accordingly.











connectionid_t tcons_open( sap_t  dest_SAP, 
			   sap_t  src_SAP 
			   qos_t  qos ) 
   
   Attempts to build a bidirectional connection extending from src_SAP
   to dest_SAP with the desired qos.  A connection may be particularly
   scheduled across the network and allocated well-defined bandwidth and
   timing characteristics.  dest_SAP must be fully specified.  src_SAP
   may be fully specified or can have wildcards for the address and/or
   port.  Return Codes, >= 0 is the connection ID.  < 0 are error codes;
   remote host unreachable, remote host refused connection, unable to
   aquire resources






void tcons_listen( sap_t    dest_SAP, 
		   sap_t    src_SAP,
		   void *   payload,
		   int	(*CB_request) (sap_t  src_SAP, sap_t  dest_SAP, qos_t QOS, void * payload )
		   void (*CB_establish) (connectionid_t connID, sap_t  src_SAP, sap_t  dest_SAP, qos_t QOS, void * payload ) )

   Registers a persistent connection listen for a given dest_SAP.  A
   dest_SAP may have no more than 1 listen.  Additional tcons_listen()
   calls against a dest_SAP updates the listen state with the new
   parameter values.  A listen may be cancelled by making both callbacks
   NULL.  src_SAP identifies the remote endpoint that may connect to the
   given dest_SAP.  src_SAP may be fully specified, or may have
   wildcards for address and/or port.  CB_request is called when a
   connect request arrives for the given dest_SAP from the given src_SAP
   with the given QoS.  The payload parameter supplies
   application-specific data to the callback function.  If the callback
   returns -1, the connect request is rejected, otherwise it is
   accepted.  The CB_request callback is only used to allow the
   application to approve or refuse the connection request.  The
   application must not allocate state inside the CP_request callback,
   nor if the connection is accepted, should it assume the callback to
   CB_establish will occur immediately, soon, or at all.  If CB_request
   is NULL, all connection requests are accepted.  CB_establish is
   called by TCONS once the accepted connection between the two hosts is
   completed and is prepared for data exchange.  The application must
   retain the given connectionID in some application-dependent manner.






int tcons_send(	   connectionid_t connID,
		   void           *data,
		   size_t         length, 
		   qos_t	  qos,
		   void           *payload,
		   void (*CB_complete) (void * data, size_t length, int result, void * payload) )

   This function attempts to deliver the given data unit to the remote
   end of the connection.  The effective qos of a given transfer is a
   function of the class of connection and the per-transfer qos.
   Connections have some qos assigned at setup time, so redundant or
   inappropriate elements of the per-transfer qos parameter are ignored.
   Connectionless channels accept qos only for each transfer.  Not all
   qos combinations are supported in all circumstances, TCONS ignores
   unsupported parameters and assumes defaults as required.  Refer to
   the qos element documentation for information about which are
   applicable under what circumstances.  The payload parameter allows
   the application to supply additional data to the CB_complete routine
   when it is invoked.  The CB_complete callback is called by TCONS when
   TCONS has finished with the passed data and it may be used again by
   the application.  For guaranteed transfers, this indicates the remote
   host has received and acknowledged the data unit.  For non-guaranteed
   transfers, this indicates the first data-link through which the data
   unit was transferred has accepted the data unit.  Non-guaranteed
   transfers are never acknowledged by the remote host.  A NULL value
   for the CB_Routine will cause this call to block, only returning when
   the data unit has been delivered in accordance with the qos or a
   failure has occurred.  result indicates the completion of the send,
   if 0 the packet was sent to the remote host else -1 indicates TCONS
   was unable to deliver the packet according to its qos.  Potential
   error codes are; unable to accept buffer, half-open, not connected







int tcons_receive_ev(	connectionid_t connID, 		
			void *	       data,
			size_t	       length,
			void *	       payload,
			void (*CB_Routine) (void *data, size_t length, void *payload, connectionid_t connID) )

   This routine registers a call-back routine that is called by TCONS
   when the defined buffer has been filled with an incoming packet bound
   for the given connID.  All connIDs' may have multiple receive event
   indications registered to them.  Once a buffer is filled, the
   application must call this function again, specifying all parameters
   again if the buffer is to receive another packet.  Returns 0 if
   receive is accepted by TCONS, else <0 for errors; unable to set up
   the receive, connection half-open, not connected







int tcons_receive_po(	connectionid_t connID,
			void *	       data,
			size_t	       length,
			struct timeval* timeout )

   Waits for the given timeout duration to receive one data unit on the
   given connID.  If timeout is NULL, the routine will wait forever.  If
   timeout is supplied, it is interpreted as follows; timeout = 0 -
   return immediately, n - time to wait

   Different TCONS implementations may have different receive queueing
   methodologies, an application must not assume TCONS will receive a
   packet if a call to this function is not waiting for it.  If a
   definite receive queuing policy is desired, tcons_receive_ev() should
   be used instead.

   Return code is -1 if timeout occurred, otherwise it is the number of
   bytes in the packet.
 



int tcons_close( connectionid_t connID )

   Called when an application desires to close a connection.
   tcons_close() does not affect connectionless identifiers.  Either end
   of a connection may close it.  Once a connection is closed, further
   send/receive attempts upon it will fail with the appropriate error.

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