# 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.