General comments

• ACNET communication to VxWorks front-ends occurs on UDP port 6801
• Acnet trunk 230 is for pseudo-nodes, e.g., open-access clients, these nodes are not accessiable over acnet. These pseudo nodes were created for alarm mapping etc. See Kevin Cahill for more information.
• Based on the while-loop in msgrecv() of ~briegel/vw/Acnet/msgrecv.c it appears that multiple ACNET packets may be transmitted in a single UDP datagram.  msgrecv() is called by iprcv() to process incoming UDP datagrams.
• Based on the ACNET network representation, it appears that
1. ACNET does not support odd-length packets.
2. Integer data in an ACNET packet which is not word(2-byte) aligned will have a non-contiguous network representation.

ACNET network representation

• Conceptually ACNET network representation of data involves two steps
1. All integers use little-endian representation
2. Swap the even and odd bytes of the packet
• Therefore a word-aligned 2-byte integer will use big-endian representation but a word-aligned 4-byte integer will have a middle-endian representation.  And word-aligned strings like "MISCBOOT" will be represented as "IMCSOBTO" in an ACNET packet.
• In ACNET design note 22 some data does not have a clearly defined type.  For example is an SSDN an array of 8 1-byte integers, an array of 4 2-byte integers, or a single 8-byte integer.  This distinction is important because the network representations of these SSDN interpretations would be different.    The SSDN in a RETDAT request packet is interpreted as an array of 8 1-byte integers for the purposes of determining network representation.

 UDP ACNET header

 

Length(bytes)	Field Description	Type
1	Control flags	1-byte integer see below
1	Status flags	1-byte integer see below
2	ACNET global error	2-byte integer
2	Host address 1	structure see below
2	Host address 2	structure see below
4	Taskname	4-byte integer
1	Destination/source task id	1-byte integer
1	Sequence packet	1-byte integer
2	Message stamp	2-byte integer
2	Size (in bytes including this header)	2-byte integer

 
• This header is the first thing in data of the UDP datagram.  That is, this header is the first thing in the buffer returned from the UDP recvfrom() call.  The data of the ACNET  packet follows immediately after this header.
• Which one of the host addresses is the destination which one is the source depends on whether the packet is an unsolicited message or request or a reply.  See host address comments below.
• The ACNET global error is to be 0 when there is no error.   If there is an error, it should contain a standard facility-error code.  The facility is in the least significant byte, the error in the most significant  byte.   The facility is an unsigned integer.  The error is a signed integer.  Errors less than 0 indicate failure. Errors greater than 0 indicate conditional success or status, e.g., pending.
• Host address 1 is the address of the host to which the unsolicited message or request that initiated the dialog was sent.  That is, this is the address of host which will send the reply.
• Host address 2 is the address of the host which sent the unsolicited message or request that initiated the dialog.
• Task"name" is a 4-byte integer.  Typically, the value is the encoding of a 6-character string obtained with the RAD50L macro in  clib_include:macro.h   Example:  RAD50L("SETDAT") returns the value 0x193C779C.   The network representation of this integer will be the bit-string 779C193C, per the representation rules given above.  The Hex field of the D38 application displays the value returned by the RAD50L macro for each task's name.  This is the taskname of the task on host 1, i.e., it is the taskname of the task to which the request that initiated the dialog was sent.
• Destination/source task id is used to identify who should receive replies.  When a request is sent this byte will have an integer which identifies the task on host 2 which sent the request.  When a reply is sent the task id which was sent in the request should be sent back in this byte, so that ACNET on host 2 can determine which task should receive the reply.
• The sequence packet field is used for packeting information which is done for transports with small frame sizes, e.g., Ethernet.  Packeting refers to the disassembling and reassembling of large packets.  For UDP packeting is not done and this field is set to 0.  This field was original intended for a checksum, which has never been implemented.
• The message stamp is used  along with host address 2 to uniquely identify a dialog.  This host/stamp pair is what allows an application that is receiving multiple RETDAT replies to correlate replies with requests, since no such identification is contained within the RETDAT reply itself.  This host/stamp pair is also what identifies what dialog is to be canceled when the cancel bit is set.

Control flags

Mask	Description	Value	Meaning
0x01	Multiple replies	0x00	Single reply
		0x01	Multiple reply
0x06	Packet type	0x00	Unsolicited message
		0x02	Request
		0x04	Reply
		0x06	Reserved

 
 
• The most-significant nybble of the control flag is a reply sequence number, which is sent along with replies, both single and multiple replies.   This sequence number is used to detect missing replies, although the strategy is not foolproof.   The sequnce number starts at 1 and counts up with each reply eventually rolling over.  Some ACNET speakers, e.g., those using Charlie's ACNET, do not support this and they will always send a zero reply seqence number.
• The multiple reply flag should be set for requests which desire multiple replies and for replies which are in response to requests which requested multiple replies.  If a multiple request can not be serviced do to some error, the requesting task should respond with a final reply that has the multiple reply flag clear and the ACNET global error set to indicate the error.  Otherwise it should be clear.
• Replies are not sent in response to unsolicited messages (USM).
• Exactly one reply is sent in response to a single reply request.
• Replies will be sent indefinitely for a multiple reply request.  Replies to a multiple reply request are stopped by sending an explicit cancel USM.
 

Status flags

 

Mask	Description	Value	Meaning
0x02	Cancel	0x00	not a cancel
		0x02	cancel

 
• A packet with the cancel flag set should always be a dataless unsolicited message (USM).  The dialog to be canceled is indicated by the combination of the host address 2 and message stamp.

Host address structure

 

Length(bytes)	Field Description	Type
1	Trunk	1-byte integer
1	Node	1-byte integer

 
• In applications, e.g., D31, which display the address as a single two-byte integer, the most-significant byte is the trunk and the least-significant byte is the node.  Therefore, 9CC, aka VXTSTX, means trunk 9 and node CC.

Charlie's ACNET routines

These comments are based on the source code in ~briegel/vw/Acnet, which is the directory containing the library that the main injector vacuum front-end links with.
Charlie's routines correspond somewhat to the old ACNET API used on the VAXen.  There is documentation available on the old VAX ACNET API via oldclibh * <routine>.  This documentation is a starting point for figuring out Charlie's ACNET API.  The comments below address Charlie's API specifically.
 

ntcreq()

This routine is used to check/get requests and unsolicited messages.  Its flag argument indicates what flags were set in the ACNET packet.  One can tell a request from a USM by the F_REQ flag.  One can tell if a request is a multiple reply request with the F_MLT flag.  One can tell if a USM is a cancel by the F_CAN flag.  There is also another flag F_RTL which is not an ACNET flag.  F_RTL is set if the user-supplied buffer was too small to hold the packet.  If one uses ACNET allocated buffers this situation will not occur since ACNET  will allocate an appropriately sized buffer for each packet.   One specifies ACNET allocated buffers by passing a NULL buffer pointer and 0 length to ntrreq().    Although MOOC checks F_RTL, it should not need to since it use ACNET allocated buffers.

ntcrpy()

This routine is used ot check/get replies.