This chapter presents information you must know before implementing an LCP or DCP. Please read these sections whether you are implementing an LCP, a DCP, or both:
Section 2.1 shows how OpenVault starts its modules.
Section 2.2, tells how OpenVault tracks information.
Section 2.3, describes how the modules communicate.
Because it is composed of different modules working together, OpenVault booting is critical for correct operation. This section describes how OpenVault assembles itself, either at system boot time or when recovering from partial failure of the system.
The MLM server initiates a sequence to bootstrap a functioning OpenVault system. Each component boots independently, reading its own configuration file, which contains just enough information to initialize that particular component. Remaining information is derived from the state of a device, persistent storage, or from parameters compiled into a particular component. Configuration files vary greatly from component to component. The session initiation sequence is the same for all components, and allows a component to identify itself by name, type, and the language versions that it supports.
The MLM server should be the first component to initialize itself. If the MLM server reboots, all LCP and DCP connections to it are lost. Procedure 2-1 describes the steps the MLM server takes during booting:
Procedure 2-1. Booting MLM Server
Read its configuration file.
The LCP or DCP developer does not need to be concerned about this file.
Accept connections from booting DCPs and LCPs.
The communications layer establishes TCP keepalive sockets. If the connection is lost, the MLM server tries to re-establish the connection every two minutes.
Service other client connections and AAPI or CAPI requests.
The MLM server accepts client connections as they arrive. AAPI and CAPI requests are fulfilled if the resources needed to service them are available.
Each LCP and DCP must also initialize itself. For details on LCP booting, see Chapter 4, “Programming a Library Control Program (LCP)”. For details on DCP booting, see Chapter 6, “Programming a Drive Control Program (DCP)”.
The OpenVault persistent store is implemented as a database subsystem that resides in the MLM server. This is a multiuser, in-memory relational database subsystem whose clients are the modules that make up core OpenVault services. Each OpenVault module is linked with a C library to handle the following activities:
One important OpenVault process is the Catalog Manager, which handles database startup and recovery, manages the on-disk transactional log file, and takes periodic snapshots of the database.
The LCP or DCP developer does not need to be concerned about details of the OpenVault database. The MLM server handles database operations triggered by LCP and DCP events or by CAPI requests from client applications transparently. LCPs and DCPs interact with the persistent store through the ALI/R or ADI/R language.
The OpenVault interfaces ALI, ADI, CAPI, and AAPI are based on message passing. Only ASCII strings travel across the sockets. OpenVault client and control program processes communicate with the MLM server through TCP/IP sockets. The hello-welcome sequence establishes an IPC connection based on a TCP socket.
Once an IPC connection has been established, the entity at either end of the connection may send and receive commands compatible with the negotiated language and version. The sender of a command generates a unique task ID for that command. The task ID is used in subsequent responses to that command. The sender may also use the task ID to cancel the original command or check command status.
To allow partial upgrades and peaceful coexistence of different language versions, OpenVault includes a session initiation facility to negotiate language version. When connecting to the MLM server, a client or control program announces which language it uses, and which versions of the language it understands. The MLM server then selects one version and tells the client which one to use for the current session.
LCP and DCP programmers working in the C language can use a library routine that encapsulates the hello and welcome exchange to establish a session. For an LCP, version negotiation is built into the ALIR_initiate_session() function. For a DCP, version negotiation is built into the ADIR_initiate_session() function.
The OpenVault session is demarcated by version negotiation (hello and welcome) at the beginning, and close of session (goodbye) at the end.
Before a session can be established between the initiator and its recipient, authentication is needed. OpenVault employs public key session verification to provide a modicum of security while still avoiding export restrictions.
As an example, assume that Alice represents the client that initiates communication with the MLM server (the client could be a DCP, LCP, or client application). Bob represents the MLM server. The authentication process begins with Alice sending her name to Bob. Bob replies by generating a 32-bit random number (R1) and sending it to Alice as a challenge. Upon receiving this number, Alice encrypts it with the key she shares with Bob and sends this value, along with another 32-bit random number she has generated herself (R2) to Bob. After checking to make sure that Alice has successfully encrypted R1, Bob then encrypts R2 and generates a third random number (R3). Bob now sends the encrypted R2 and R3 to Alice. Alice verifies that R2 has been properly encrypted and then decrypts R3 and stores it as the session key.
Infrastructure developers do not need to be concerned about details of the OpenVault authentication method. The OpenVault transport layer handles authentication requests from client applications transparently.
A communication session between the MLM server and a client or control program employs a stylized sequence of phases. Since the interface is a full-duplex bidirectional peer-to-peer interface, this applies to both directions of a session. There are three phases:
Associated ALI/R or ADI/R commands may intervene between transmission of a command and receipt of the corresponding final response.
Since sessions are full-duplex, each endpoint must be prepared both to read and write on a session without blocking for either. For example, if the LCP is sending but the MLM server is not responding and its buffers are full, the LCP must still be prepared to accept incoming data from the MLM server. The only permitted blocking I/O operation is a select() call. This requirement helps reduce the likelihood of deadlocks.
Figure 2-1, shows OpenVault communication layers, which are described in this section.
The function of the semantic layer is the same for both ALI and ADI. It is responsible for the following tasks:
Implementation of ALI and ADI commands
Ack processing, synchronizing commands by ensuring that a command is not sent until an acknowledgment is received for the previous command
Ready state processing Section B.3.1 in Appendix B)
Response sequencing
If an ALI or ADI command results in ALI/R or ADI/R commands being sent, in addition to the normal ALI/R or ADI/R responses for acknowledgment and final response, the intervening ALI/R or ADI/R commands should be sent in between the ack and final responses. For example, an activate enable command to a DCP usually results in the series ADIR_reponse for acknowledgment, ADIR_config, ADIR_ready, and finally ADIR_response for final response.
Detection and handling of device state changes
This can range from full asynchronous notification by a device or device controller to a control program to periodic polling of a device by the control program to detect changes. With SCSI, the device raises a unit attention condition, and sends a unit attention notification piggy-backed on a response from the SCSI device, which indicates that some device state has changed. The control program can then send additional SCSI commands to determine what state has changed, and to clear the unit attention condition.
When the control program detects state changes that affect the control program's ready state or configuration from the MLM server's point of view (for example, the library may have gone offline, or the library contents may have been altered if the library front door was detected to be opened and then closed), then the control program should update ready state and configuration information, as appropriate, and push the new ready state and configuration up to the MLM server.
The parser and generator layer uses the POSIX compliant GNU utilities Bison and Flex, and is responsible for the following tasks:
Language version negotiation and session establishment
The source files involved are ovsrc/include/hello.h and ovsrc/libs/hellor/*.
Converting commands between C data structures and ASCII representations
The ALI source files involved are ovsrc/include/{ali,lcp}.h and ovsrc/libs/ali/*.
The ADI source files involved are ovsrc/include/{adi,dcp}.h and ovsrc/libs/adi/*.
The over-the-wire ALI and ALI/R or ADI and ADI/R layer employs nothing but ASCII strings, and is responsible for the following tasks:
Transitioning between command phases (command, ack, data)
Conforming to language conventions (the parser enforces this)
All commands are designed so that the basic arguments of the command may be entered in any order. For example, these two commands are equivalent:
mount slot["#12", "vol.001", "sideA"] drive["DLT2"]; mount drive["DLT2"] slot["#12", "vol.001", "sideA"]; |
OpenVault strings are composed of ASCII characters in the range 32 to 126 (decimal). Strings must be quoted with either a double-quote or single-quote (“ or `) as shown in Example 2-1. OpenVault considers these different quote characters to be identical.
Example 2-1. Using Quote Characters in Strings
To include either quote character in a string, precede it with backslash (\). To include a single backslash character in a string, put two backslash characters in a row:
"This string contains a backslash \\ and a double quote \" character." |
Potential return value types depend on the command issued. In general, when a command is successful, the return value specification is the following:
response success text [retValue(s)] |
When a command is unsuccessful, the error return value conforms to the following specification:
response error errorSpec |
Boolean return values are predefined strings “true” and “false”.
The following modules are provided in the source code tree as an aid to LCP and DCP developers:
A generic linked list queue in ovsrc/src.GPL/server/include/queue.h
A command queuing facility and state machine in ovsrc/src.LGPL/include/cctxt.h and ovsrc/src.LGPL/common/cctxt.c
Shared LCP or DCP data structures and functions in ovsrc/src.LGPL/include/[ld]cp_lib.h and ovsrc/src.BSD/[ld]cp/common/util.c
These are intended to provide a basic framework for developing DCPs and LCPs, and also reusable software for common control program operations such as ack, attribute, error, and ready-state processing. This framework will evolve.
These modules, which are intended as a basic framework for DCP and LCP development, will evolve. They include reusable software for common control program operations such as ack, attribute, error, and ready-state processing.
LCP and DCP templates are provided to enable developers to start coding. This source code is available as a freely downloadable package: http://www.sgi.com/software/opensource/openvault/
An LCP conformance suite is in ovsrc/src.GPL/conformance/lcp, and a DCP conformance suite is in ovsrc/src.GPL/conformance/dcp. Developers should test each LCP and DCP against a conformance suite to assure compliance with OpenVault specifications. Although there is no formal LCP or DCP certification program, this is the next best thing.
Each conformance suite simulates the MLM server's interaction with an LCP or a DCP, and attempts to find certain logical errors in a control program, such as allowing ejection from an empty slot or unloading of an empty drive. See the respective README files for specific information about running an LCP or DCP conformance suite.