DECwindows Motif for OpenVMS Version 1.5 Transport Interface Notes Created: 24 September 2004 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ These notes summarize the extensive changes made to the transport code. The information in these notes supersedes that documented in the "VMS DECwindows Transport Manual". Overview ======== The transport code is now divided into the following images: DECW$LCNLIBSHR - LCN support, which can be used without the rest of the transport code DECW$TRANSPORT_COMMON - Application programming interface DECW$XPORT_SERVICES - User-written system services that support the transport DECW$XPORT_PTHREAD - Loaded dynamically if Pthread support is needed DECW$TRANSPORT_DECNET - Implementation of each transport DECW$TRANSPORT_LOCAL DECW$TRANSPORT_TCPIP DECW$TRANSPORT_LAT The specific transport images are dynamically loaded on demand by DECW$XPORT_SERVICES. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Data Structures =============== There is no longer one XTDB per transport. A new XTDB is created when the same transport is used on different port numbers, such as with server and client connections or with different protocols (ICE, X11, etc.). The following sections describe the specific changes to each data structure. XTPB Data Structure (XTPB$) --------------------------- New Flags: NULL_PORT - Indicates that a null port was specified when attaching the transport. A null port forces the transport-specific code to allocate a port number. QUEUE_COMPACT - Used to prevent a non-responsive client from blocking write operations by a server. If a free buffer for queueing a read cannot be found, this flag signals that queue compaction should be performed. Queue compaction merges the data in buffers on the input work queue to fully utilize buffer space. REATTACH - Used by the server to withstand the shutdown of the DECnet or TCP/IP networks. If a network is shutdown, periodic attempts are made to reattach the transport. New and changed fields: ALLOC_SIZE - Control how the server allocates memory for received EXTEND_SIZE connections. Previously, these were global across all transports. Now, they are per transport and the transport code uses the largest setting from any of the transports. CALLBACK_ARG - A quadword passed to the CONNECT and ABORT functions, the API sets this as an attribute of the transport. DISPLAY_NUM - Only used by X11 for compatibility. New code uses the port field as text. I_TIMEOUT_ADDR - Simplified access to I_TIMEOUT and O_TIMEOUT that can handle O_TIMEOUT_ADDR null timeout values. PORT_LEN - Port number in a canonical format defined by the PORT transport-specific code. IXTCC Data Structure (IXTCC$) ----------------------------- New and changed fields: LCN_NUMBER - Logical Connection Number (LCN) used to indicate when input is available or a write buffer is free. OPEN_STATUS_ADDR - Specifies where to put the status from an asynchronous open operation. USER_RESERVED0 - The user-reserved values are normally held in the XTCC. USER_RESERVED1 However, they can be specified as arguments to an open operation before the XTCC exists. This is a temporary storage location until the XTCC is created. XTCC Data Structure (XTCC$) --------------------------- New flags: IN_AST_USING - Set when the connection is processing an AST to OUT_AST_USING prevent another thread from closing the connection. OUT_AST_IN_PROG - Used for output similar to IN_AST_IN_PROG. New and changed fields: DEPTH_COUNTER - Counts the concurrent calls of DECW$XPORT_READ. IO_IOSB - These have all been removed. OUT_IOSB OW_IOSB IN_WAIT_TICKS OUT_WAIT_TICKS OUT_FREE_SPACE - Counts the number of free bytes in the buffer at the tail of the output work queue. REENTERED_READ - Tracks when DECW$XPORT_READ has been called reentrantly. XTCB Data Structure (XTCB$) --------------------------- No changes. XTCQ Data Structure (XTCQ$) --------------------------- Only the SRP related flags are used. A waiting process is alerted when an entry has been inserted in either the small XTCB or large XTCB free queue. Code waiting for a large XTCB when a small XTCB is available must first use the available small XTCB and then wait for the remaining space to become available. XTDB Data Structure (XTDB$) --------------------------- New flags: RUNDOWN - Indicates that the image is in rundown mode, and the transport has started rundown processing. New and changed fields: CHK_OBJTYP - These have all been removed. CHK_OBJNAM_LEN CHK_OBJNAM_ADR CHK_FLAG PROTOCOL_LEN - Name of the protocol being supported "X11", "ICE", etc. PROTOCOL REATTACH_FLINK - These maintain a list of transports that are to be REATTACH_BLINK processed when the reattach timer expires. XTFT Data structure (XTFT$) --------------------------- The values of the REQUIRED0 and REQUIRED1 fields have been changed. New routine addresses have been added: - DISCONNECT - TRANSLATE_PORT - LOCAL_NODE - GET_KRB5_FAMILY - GET_KRB5_REM_ADDRESS - COMPLETE_ACCEPT The GET_KRB5_FAMILY and GET_KRB5_REM_ADDRESS functions are used to support Kerberos authentication. Kerberos only specifies support for the TCP/IP protocol. For all other transports these addresses should be specified as zero in the XTFT data structure. The COMPLETE_ACCEPT function is used by TCP/IP to execute a user mode reverse name translation. For all other transports this address should be specified as zero in the XTFT data structure. A number of placeholder addresses are reserved in the XTFT data structure. These addresses should be set to zero and are currently not used. In future releases they may be changed for transport-specific functions and allow changes for one transport without changing all others. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Transport-Common Routines ========================= New functions: DECW$$XPORT_CLOSE Closes a transport connection that has been rejected by the server. It takes the XTCC as argument. DECW$$XPORT_DISCONNECT Frees transport common resources for a connection that has been disconnected, and calls the transport-specific disconnect function. Call this from user-mode passing the XTCC as argument. DECW$$XPORT_INSQHI DECW$$XPORT_REMQHI DECW$$XPORT_REMQTI Provides a safe means for inner mode code to modify queues of user mode data, which can also be accessed from inner mode. These functions check that only data that has user mode access is modified. DECW$XPORT_LCN_ALLOC_PROT DECW$XPORT_LCN_ALLOCATE DECW$XPORT_LCN_CLEAR_EXCEPT DECW$XPORT_LCN_CLEAR_READ DECW$XPORT_LCN_CLEAR_WRITE DECW$XPORT_LCN_FREE DECW$XPORT_LCN_SET_EXCEPT DECW$XPORT_LCN_SET_READ DECW$XPORT_LCN_SET_WRITE DECW$XPORT_LCN_UNPROT These functions are LCN functions documented in the New Features manual. DECW$XPORT_OUT_NOTIFY_USER Same as DECW$XPORT_IN_NOTIFY_USER, except it uses the output AST fields. It provides safe output notification when multiple kernel threads are in use. DECW$$XPORT_REQUEST_REATTACH Passed an XTDB. Puts the XTDB on a list of transports to periodically attempt to attach to. Changed functions: DECW$XPORT_IN_NOTIFY_USER This has been made safe against multiple kernel threads. It sets a flag on entry to defer closing, and closes the connection if a user-mode close was requested while the AST was in progress and there are no notification ASTs queued or in progress. DECW$$XPORT_ASYNC_OPEN An additional flag parameter has been added that is passed through to the transport specific code. For the TCP/IP transport this flag is used to indicate whether the address is in binary sockaddr(_in6) format or is a host address character string. The following functions remain unchanged: DECW$XPORT_ACCEPT_FAILED DECW$XPORT_ALLOC_INIT_QUEUES DECW$XPORT_ALLOC_PMEM DECW$XPORT_ATTACHED DECW$XPORT_ATTACH_LOST DECW$XPORT_COPY_AND_WRITE (in DECW$TRANSPORT_COMMON) DECW$XPORT_DEALLOC_PMEM DECW$XPORT_DEALLOC_QUEUES DECW$XPORT_FAO DECW$$XPORT_FREE_INPUT DECW$$XPORT_OPEN_COMPLETE DECW$XPORT_READ_COMPLETE DECW$XPORT_REATTACH_FAILED DECW$XPORT_REFUSED_BY_SERVER DECW$XPORT_UNEXPECTED_MESSAG DECW$XPORT_UNKNOWN_LINK DECW$$XPORT_VALIDATE_STRUCT DECW$XPORT_VALIDATE_STRUCT_JSB DECW$$XPORT_WRITE ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Transport-Specific Routines =========================== The transport-specific routines must be provided by each transport-specific image. This section describes changes and additions to the functionality that the transport-specific images must provide in their implementations. New functions: XTFT$A_DISCONNECT Must free any transport-specific resources associated with the connection and not already freed by the XTFT$A_CLOSE call. This function is called in exec mode with the XTCQ, XTPB etc. still valid. These structures are then freed by the caller. Arguments: ITCC Type: IXTCC Access: read/write Mechanism: reference The IXTCC of the connection being closed. XTFT$A_LOCAL_NODE Must return the name of the local node for this transport. Arguments: BUFADDR Type: character array Access: write Mechanism: reference Set to the local node name. Truncated if the buffer length is too small. BUFLEN Type: longword Access: read/write Mechanism: reference Input as length of buffer; output as length used. XTFT$A_TRANSLATE_PORT Ensures that the transport only attaches to a port once when different but equivalent ways of identifying a single port are used. The function must convert from the user's input to a canonical format defined for the specific transport. The user can request that the function allocate a unique port name by supplying a null port value. Each call of this function with a null port value must allocate a new port name. This function can be called in user or exec mode. Arguments: SERVER_ADDR Type: longword Access: read Mechanism: reference Used for compatibility with older clients and only applies to the X11 protocol. If a null argument, then the port is given by the PORT_NAME_ADDR argument. If not a null argument, the argument value is the X11 display server number. PORT_NAME_ADDR Type: character array Access: read Mechanism: reference Provides the user-supplied port name or number. Only used when SERVER_ADDR is null and PORT_NAME_LEN is not zero. PORT_NAME_LEN Type: word Access: read Mechanism: value Specifies the length of the PORT_NAME_ADDR buffer. A zero value is used when the user supplies a null port. This indicates that the transport is to assign a port for the user. NULL_PORT Type: longword Access: write Mechanism: reference Set this to TRUE or FALSE to indicate whether the port provided was null and assigned by the transport. A zero-length port is always to be treated as a null as should a port name of "0". Specific transports may also treat other port names as null. CANONICAL_PORT Type: character array Access: write Mechanism: reference If NULL_PORT is set FALSE, then set this to the port name in a canonical format (a single form that all equivalent ports match). For example, "1" might be the canonical format for "1" and "01". CANONICAL_PORT_LEN Type: longword Access: read/write Mechanism: reference Initially the length of the CANONICAL_PORT buffer. Set to the length of the canonical port string. PROTOCOL Type: character array Access: read Mechanism: descriptor The protocol being supported. Protocol strings are standard and defined in XPORTDEF/XPORTCOM, using macros such as DECW$S_X11_PROTOCOL. XTFT$A_COMPLETE_ACCEPT Executes in user mode to complete processing of an accept sequence by the server. For example, with the TCPIP transport it executes the reverse name translation. XTCC Type: XTCC Access: read/write Mechanism: reference The XTCC of the connection being accepted. ITCC Type: IXTCC Access: read Mechanism: reference The IXTCC of the connection being accepted. GETNAMEINFO Type: function pointer Access: read Mechanism: value The address of the DECC$GET_NAME_INFO function needed by the TCPIP transport. Changed functions: CLOSE_AND_DEALLOCATE_AST This function should be declared as a user-mode AST so that existing user-mode ASTs can be processed to completion. The sole operation it should do is to call the DECW$$XPORT_DISCONNECT function passing the address of the XTCC. That function executes common disconnection processing and then calls the transport-specific disconnect in exec mode for transport-specific processing. DECW$TRANSPORT_INIT This function is called only once even if the transport is attached multiple times. If it fails to return an XTFT, then the common code records that it is an invalid transport and fails any additional attach attempts for this transport. DETACH_AND_POLL To execute the polling function, call DECW$$XPORT_REQUEST_REATTACH function and pass the address of the XTDB. This will handle the issuing of periodic attach attempts. FREE_INPUT_AST No change. REATTACH_AST This function is no longer required. A common reattach timer and AST is now available from the common services and initiated through the DECW$$XPORT_REQUEST_REATTACH function. TRANSPORT_OPEN_CALLBACK This must set the write state on the LCN. This state is used to indicate that there is space available for writing on the connection. The state also indicates to an asynchronous open that the open operation has completed. TRANSPORT_READ_AST This must allocate an IXTCC, an LCN in the IXTCC, create the connection XTPB and then call DECW$XPORT_ALLOC_INIT_QUEUES to allocate the XTCC and the data queues. If all is well, this function must end by declaring a user mode AST to call the TRANSPORT_OPEN_CALLBACK. TRANSPORT_READ_QUEUE No change. WRITE_AST After inserting the buffer in the free queue, this function must set the LCN write state. If the connection has died this function should set all three states in the LCN. XTFT$A_ATTACH_TRANSPORT If the port passed in the XTPB was null, then this function must set the XTPB port fields to the port actually allocated by the transport. Attach transport does not call the server's connection request routine. This happens when the TRANSPORT_READ_AST receives a connection request. If the attach fails and the reattach flag is set in the XTPB, then DETACH_AND_POLL should initiate polling. XTFT$A_CLOSE The actual process of closing the connection must be delayed until after user-mode ASTs have been processed. This function should set the DYING flag and deassign I/O channels to prevent new ASTs being delivered. Then it should declare CLOSE_AND_DEALLOCATE_AST in user-mode to complete processing. XTFT$A_EXECUTE_FREE No change. XTFT$A_EXECUTE_WRITE No change. XTFT$A_FREE_INPUT_BUFFER If the read failed then this function should set all LCN status bits. The code must validate the size of the read requested to make sure it doesn't run over the end of the buffer. The XTCB is in user mode accessible memory and a concurrent kernel thread can modify it at any time. XTFT$A_OPEN The server argument has been removed. The server number or port can be obtained from the associated XTPB. An additional flag parameter has been added. XTFT$A_RUNDOWN This function can now be called multiple times - once for each protocol (and port for servers). XTFT$A_WRITE_USER No change. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Transport Support Macros ======================== New macros: XPORT_OUT_WRITE_DISABLE_IXTCC XPORT_OUT_WRITE_ENABLE_IXTCC XPORT_IN_FREE_DISABLE_IXTCC XPORT_IN_FREE_ENABLE_IXTCC These use an IXTCC to identify the flags and are safe to call in any mode. The previously existing equivalents use an XTCC and must only be called from user mode. Changed macros: Although there are still SRP and LRP macros all operations only work on the SRP flags. A single set of flags is used to indicate buffer availability for writes. XPORT_OUT_NOTIFY_SEND Like XPORT_IN_NOTIFY_SEND, this macro ensures only one output AST is queued. XPORT_ABORT_SEND This macro does not call the function nor declare the AST if the connection is marked for close. If called in user mode, it calls the function directly If called in exec mode, it declares a user-mode AST. Deleted macros: The following unused macros have been deleted: XPORT_IN_NOTIFY_WAIT XPORT_OUT_NOTIFY_WAIT XPORT_WRITE_WAIT XPORT_XTCB_FILLED