Compressed CKD Dasd Emulation

Contents

• Introduction
• Shadow Files
• File Structure
• Methodology
• Quick Start
• Using Shadow Files
• Options
• Utilities
• FAQ
• Changes
• Bugs
• cckddump os/390 hlasm program

Introduction

A cckd file contains track images, which may be compressed or uncompressed, and overhead blocks which are headers, lookup tables, and free space. Compressed track images may be compressed by zlib or bzip2.

Track images are addressed by track number using a two table lookup method: track number divided by 256 (trk >> 8) indexes into the primary lookup table, which contains the file offset to the secondary lookup table; the remainder of track number divided by 256 (trk & 0xff) indexes into the corresponding secondary lookup table, which contains the offset and length of the track image.

There is a single primary lookup table and a variable number of secondary lookup tables. The maximum number of secondary lookup tables is the number of tracks for the device type divided by 256, rounded up. For example, a 3390-3 contains 50085 tracks and would require at most 196 secondary lookup tables.

A regular CKD file contains a 512 byte header followed by track images, each taking the same amount of space: the maximum track size. The offset of a track image can be readily calculated by the track number:

A cckd file can take significantly less file space than a regular CKD file because

• A track image only occupies its length in the file and not the maximum track size
• A track image may be compressed, reducing its length
• Unused or null tracks do not occupy any space at all

Shadow Files

Shadow files are implemented using the same file structure as base cckd files. By default, there can be up to 8 shadow files in use at any time for an emulated CKD device. The base file is designated file [0] and the shadow files are files [1] up to file [8]. The highest numbered file in use at a given time is the current file, where all writes will occur. Track reads start with the current file and proceed down until a file is found that actually contains the track image.

A shadow file, then, contains all the changes made to the emulated CKD dasd since its creation, until the creation of the next shadow file. The moment of the shadow file's creation can be thought of as taking a snapshot of the current emulated CKD dasd at that time, because if the shadow file is later removed, then the emulated CKD dasd will revert to the state it was at when the snapshot was taken.

Using shadow files, you can keep the base CKD file on a read-only device such as cdrom, or change the base CKD file attributes to read-only, ensuring that this file can never be corrupted.

Hercules console commands are provided to add a new shadow file, remove the current shadow file (with or without backward merge), compress the curent shadow file, and display the shadow file status and statistics.

CCKD File Structure

• CKD_P370    Regular CKD file
• CKD_C370    Compressed CKD file
• CKD_S370    Shadow CKD file

Following the L1TAB, in no particular order, are L2TABs, compressed track images, and free spaces.

L2TABs contain 256 8-byte entries,and each are, consequently, 2048 bytes in length. Each entry contains the offset and length of a track image. If the offset is 0x00000000 then the track image is null; if the offset is 0xffffffff then the previous file should be searched instead.

A compressed track image contains the following two fields:

• A track header, also called a home address or a track index. The track header is never compressed.
• The track image, beginning with the R0 count and ending with the end-of-track marker, which is a count field containing all hex 0xff's. The track image may or may not be compressed.

The HA contains 0CCHH, that is, a byte of zeroes, 2 bytes indicating the cylinder of the track, and 2 bytes indicating the head of the track on the cylinder. Both CC and HH are stored in big-endian byte order. The track is computed by

Free space contains a 4-byte offset to the next free space, a 4-byte length of the free space, and zero or more bytes of residual data.

The minimum length of a free space is 8 bytes. Since free space is ordered by file offset and no two free spaces are adjacent, offset in the free space entry is always greater than the current free space offset + the current free space length, unless the offset is zero, which indicates the free space chain is terminated.
The free space chain is read when the file is opened for read-write and written when the file is closed; while the file is opened, the free space chain is maintained in storage.

Methodology

The interface

All Hercules emulated devices have standard interface routines described by the DEVHND structure. These routines are

init	Device initialization (attach)
exec	Device execute channel command
close	Device close (detach)
query	Device query
start	Device channel program start
end	Device channel program end
resume	Device channel program resume
suspend	Device channel program suspend

Emulated CKD DASD devices have two additional routines:

ckdrdtrk	Read CKD track image
ckdupdtrk	Update CKD track image

ckdrdtrk is called whenever a SEEK type channel command is executed and ckdupdtrk is called whenever any of the various WRITE channel commands modifies the current track image.

The cckd code implements the following routines:

cckddasd_init_handler	cckd device initialization (attach)
cckddasd_close_device	cckd device close (detach)
cckd_start	cckd channel program start/resume
cckd_end	cckd channel program end/suspend

The cache

The implementation is cache table driven. The cache table contains 16 to 1024 entries, each representing a track image, and is shared by all cckd devices. Each entry contains a pointer to a track image buffer which is 64K bytes. That is, every 16 entries represents 1M of buffer space. The size of the cache can be changed by a configuration file statement or by a hercules console command.

Each entry can be in one (or certain combinations) of the following states:

active	A channel program is active for the device and the track image is the last SEEKed track image.
updated	The track image has been updated by a WRITE command.
write	The track image is not active and has been updated and is eligible to be written.
reading	The track image is currently being read.
writing	The track image is currently being written.
inactive	The track image is not busy and is eligible to be stolen

When the ckdrdtrk routine is called, and the track to be read is not the active track, then a track switch event occurs. The cache is scanned to see if it contains the track image. If it does, then a cache hit occurs else a cache miss occurs.

In the case of a cache hit, if the entry status is reading or writing then the code waits for the read or write to complete. If the entry is write-pending, then the entry is changed back to updated.

Otherwise, for a cache miss, the oldest inactive cache entry will then be stolen. If no inactive cache entry was found then the cache is flushed and the code will have to wait for an inactive cache entry to become available. This is called a cache wait event. When the cache is flushed, all cache entries that have been updated and are not active are set to write-pending and the writer thread is signalled. After an entry has been stolen the track image will then be read and uncompressed. If sequential access is detected then track readaheads will be scheduled.

L1 tables

The L1 tables, or primary lookup tables, contain the file offsets to each L2 table, or secondary lookup table. Each L1 table 4-byte entry represents 256 track images and there is an L1 table for the base file and each opened shadow file (if any). These tables are memory resident.

The L2 cache

The L2 tables, or secondary lookup tables contain the file offsets and lengths of 256 track images. Each table is 2K in length. These tables are cached in the l2cache, which is shared for all cckd devices. The cache can contain 128 (512K) entries to 1024 entries (2M). Each cckd device has one active l2cache entry implying that, architecturally speaking, there can be no more than 1024 cckd devices. If this is a problem for you then I'll buy you a beer ;-)

The size of the l2cache can be specified by a configuration statement or changed by a hercules console command. If a cache miss occurs and no inactive entries are found, then the cache is automatically extended (unless the 1024 entry barrier would be crossed).

L2 tables are read but never written. Instead, as track images are written, the individual 8-byte L2 entries are updated in the file.

Writing

Whenever the ckdupdtrk is called, indicating the active track image has been updated, the updated flag bit is turned on for the cache entry. However, the updated cache entries are never scheduled to be written until a cache flush occurs (routine cckd_flush_cache). A cache flush occurs whenever a cache entry couldn't be stolen during read or at the beginning of the garbage collection cycle.

When a cache flush occurs, all cache entries that are updated (but not active) get the write-pending bit turned on and one of the writer threads is signalled (or created).

The writer thread selects the oldest cache entry with the write-pending bit on and changes the status to writing. If there are other writes pending and other writer threads are waiting then they are signalled. Otherwise if there are writes pending and the maximum number of writer threads hasn't been created yet, then a new writer thread is created.

The writer thread, because it performs track image compression, is cpu intensive. Therefore, the writer thread resets its priority to 1 below the cpu thread(s) (except under Cygwin (Windows)). In periods of write stress then the level of compression is downgraded. Write stress occurs when more than a quarter of the cache entries are pending write, or when there are threads waiting for a cache entry, or when a thread is waiting for this track image to be written. When a track image is written under stress, a bit is turned on in the track image so that the garbage collector can later rewrite the track image properly compressed during a period of no stress.

A track image is always written to a new location in the file. After a successful write, its L2 entry is updated and then the space it previously occupied is freed.

The writer threads

The Garbage Collector

For some reason, this seems to be everyone's favorite routine. For me, it has to do with the fact that the garbage man only has to apparently work on Fridays ;-).

Simply, the garbage collector moves occupied spaces (track images and level 2 tables) towards the beginning of the file while moving free spaces towards the end of the file. When a free space reaches the end of the file, then the file is truncated, that is, reduced in size. Another important job the garbage collector performs is to combine free spaces to make a larger free space that will be more likely to satisfy a get space request. Finally, the garbage collector will cause track images that were written under stress to be rewritten (with optimal compression).

The garbage collector runs in a separate thread. There is a single garbage collector for all cckd devices. The collector waits for some number of seconds and then performs collection for each cckd device in turn. The wait interval and the aggressiveness parameter can be specified by a configuration file statement or by a hercules console command.

The garbage collector algorithm simply selects an occupied space after some free space, obtains a new space for that space, writes it to the new space, updates the meta-data for that space to point to the new space, frees the previously occupied space, and repeats the process until some number of bytes have been moved. In other words, the collector shifts the spaces around coherently such that in the event of a crash then the space occupies at least one space in the file (the original and possibly the new).

The garbage collector on each interval (or round ;-) flushes the cache and waits for all pending writes to complete. Therefore, the collector doesn't run while write stress is occurring.

Quick Start

You can also use the cckddump program on an os/390 system to build a compressed CKD file from a real disk that can be transferred to your Hercules machine and used right away.

Using Shadow Files

Shadow files are automatically enabled for cckd files; you must explicitly enable them for regular CKD files. To enable shadowing for a CKD device, specify

0500 3390 ../mvs/disks/mvsres.500 sf=../mvs/shadows/mvsres_1.500

If you did not specify sf= for a cckd file, or you wish to change the shadow file name for a cckd or regular file, but no shadow files are in use, then you can issue the following command on the Hercules console:

Specifying a shadow_file_name does not explicitly create a shadow file if the base file or current shadow file is able to be opened read-write. Otherwise, if the base file and all existing shadow files (if any) can only be opened read-only, then a new shadow file is created.

To explicitly create a new shadow file, issue the following command on the Hercules console:

To remove the current shadow file, issue either of the following commands on the Hercules console:

To compress the current shadow file issue the following command on the Hercules console:

To display the status and statistics for a shadow-enabled file, issue the following command on the Hercules console:

CKD Options

Generally, the defaults for all options (except sf=) should not be changed unless there is an explicit reason for doing so. If you use cckd files, then I strongly recommend that you start using shadow files. If you use regular CKD files, then you can use shadow files if you want to gain the snapshot benefit .

Utilities