# Copyright (c) 1994, 2007, Oracle and/or its affiliates. All rights reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice (including the next # paragraph) shall be included in all copies or substantial portions of the # Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # DEALINGS IN THE SOFTWARE. # # Originally submitted as PSARC/1994/377 The purpose of this document is to fast track the implementation of a shared memory based transport mechanism for the OpenWindows server and clients. This document briefly describes some of the design and implementation features of this mechanism. Section 3, entitled "User Interface for SUN_SME", describes the user visible interface. We are requesting that the interface in Section 3 be declared a Public interface. The components that have been affected by SUN_SME are Xsun and libX11. It should be noted that SUN_SME is targeted at improving benchmark performance. The current implementation uses SYSV shared memory and thus has a limit of 6 shared memory connections. Once the limit is exceeded the implementation silently falls back to a pipe connection. The plan is to eventually remove this limitation by using SunOS native shared memory mechanisms. 1. What is 'SHARED_MEMORY_EXTENSION'(SUN_SME) ? SUN_SME is an extension to the OpenWindows server with the purpose allowing clients to send requests to the server via shared memory. SUN_SME is intended to be another form of local transport mechanism like Unix sockets and the pipes mechanisms. The SUN_SME extension will be versioned so that changes can be made in a compatible manner if they become necessary. 2. How and where 'SUN_SME' gets used ? In order for a client to communicate via shared memory with the server it should have its display environment variable set to :x.y (where x is the display number and y is the screen number) and the environment variable XSUNTRANSPORT set to "shmem" before it is started. If the display variable is set to :x.y and XSUNTRANSPORT set to "shmem", local clients query the X server for the SUN_SME Extension and if it is supported the connection is set up. It should be noted that shared memory will be used for sending requests from client to server only. Replies/events and all other communication initiated by the X server will use the default IPC mechanism which is pipes in OW 3.4. Also, one shared memory segment will be set up per display connection. 3. User Interface for SUN_SME The user interface for SUN_SME will be documented in the man pages and other appropriate documentation. Following, are the visible changes that have been introduced by SUN_SME : - If the value of DISPLAY has any form other than :x[.y], the transport is determined directly from its value (using the standard, pre-existent X rules). Otherwise, the value of XSUNTRANSPORT becomes relevant. If unset, a suitable (but otherwise unspecified) local transport is used; otherwise, the transport named by its value is used, if available. In the case of shared memory, XSUNTRANSPORT must be set to "shmem". - The size of the shared memory segment between the client and server will be user configurable by setting the environment variable XSUNSMESIZE. The default value for XSUNSMESIZE will be 64K. - The xdpyinfo client will return SUN_SME in the list of supported extensions. Similarly the XQueryExtension() and XListExtensions() routines in Xlib and the corresponding QueryExtension and ListExtensions X protocol requests will indicate the existence of the SUN_SME extension. However, this information is not particularly useful to users or application developers, since the extension interfaces are intended to be Consolidation Private. 4. Implementation Features This section is for information purposes only, since the extension interfaces are Consolidation Private. The affected components are libX11 and Xsun. Currently clients communicate with the server via pipes and sockets (TCP and UDP). Our goal is to provide a shared memory communication mechanism between the client and the server. Communicating via shared memory has been measured to be more efficient than sockets/pipes. The current SUN_SME implementation uses SYSV shared memory. The final implementation will use SunOS shared memory. Some characteristics of this mechanism are : - Shared memory will be only be used for client requests. Replies from the server will be sent via pipes. - The size of the shared memory segment will be set to 64K by default. This size will be use configurable via the XSUNSMESIZE environment variable. - Variable size buffers are allocated out of the shared memory segment in a ring-like fashion. The buffers in the shared memory segment are indexed with the index containing the address and size of the buffers. The client updates the head pointer every time a request buffer is inserted and the server updates the tail pointer every time a request buffer is processed. - Requests sent by the client are packetized and sent in a buffer instead of sending one request per buffer using the same algorithm used by pipe and socket connections. The client sends a byte through the pipe to the server indicating that a request buffer has been sent. This way the server has something to poll on and the traditional select mechanism can be retained. - Suitable locking mechanisms will be used to insure consistency of shared memory between client and server under the PSO memory model when/if it becomes possible for user processes to run under PSO. - If the client runs out of request buffers it gets blocked and waits for a special reply denoted by SMEREPLY. - Large requests (for e.g. XPutImage) are split into multiple requests. - In the event that the maximum allowable shared memory has been allocated and a client attempts to initiate a shared memory connection, the transport mechanism will default to pipes.