cckd(4) 						     Kernel Interfaces Manual							   cckd(4)

NAME

       cckd - Hercules Compressed CKD DASD image file

DESCRIPTION

       Hercules DASD image file that emulates IBM mainframe DASD devices on a (usually) non-mainframe platform.  Specified in the Hercules config-
       uration file (default name hercules.cnf) to describe the DASD devices Hercules is to emulate.  Also specified as input and/or  output  file
       to  several  Hercules  utilities.  Hercules compressed DASD devices are frequently referred to as CCKD.	Hercules uncompressed DASD devices
       are frequently referred to as CKD.  Hercules CKD DASD image files are largely compatible with P/390 AWS DASD files.

TECHNICAL OVERVIEW

       The following provides a technical overview of CCKD internal structures.  Except as indicated below, data in the  following  structures	is
       stored  in  the	byte order indicated by the CDEVHDR.options CCKD_BIGENDIAN bit (the 0x02 bit).	This bit is 1 when data is big-endian byte
       order, 0 when data is little-endian byte order.

   DEVHDR
       occupies the first 512 bytes of a CKD or CCKD DASD file.  The DEVHDR contains the device type and the number of heads  per  cylinder.   Its
       contents are the same whether the DASD image is compressed (CCKD) or not (CKD).	Described by the CKDDASD_DEVHDR struct; 512 bytes in size.

   CDEVHDR
       immediately  follows  the DEVHDR, and contains fields describing the number of L1ENTs in the L1TAB, the number of L2ENTs in each L2TAB, and
       anchors the free space chain.  Described by the CCKDDASD_DEVHDR struct; 512 bytes in size.

   L1TAB
       immediately follows the CDEVHDR, and consists of L1ENT entries, each of which points to an L2TAB.  Each L1ENT is an U32	(4  bytes)  offset
       into  the  CCKD	DASD file.  The CDEVHDR numl1tab field describes how many L1ENTs are in the L1TAB.  L1ENTs are described by the CCKD_L1ENT
       typedef; the L1TAB is of variable size.	Conceptually each L1ENT describes cdevhdr.numl2tab tracks.

   L2TAB
       is pointed to by an L1ENT, and is composed of L2ENT entries, the number of which is described by the CDEVHDR numl2tab field; currently  256
       L2ENTs  in  each  L2TAB.   L2ENTs contain the offset to the TRKHDR, and the combined length of the TRKHDR and (optionally) compressed track
       data.  The CDEVHDR numl2tab field describes how many L2ENTs are in each L2TAB.  Currently, there are 256 L2ENTs in each	L2TAB.	 Described
       by the CCKD_L2ENT struct; (256 * 8) bytes in size.  Conceptually each L2ENT describes one track.

   FREEBLK
       describes  free	space  in the CCKD DASD image, anchored by the CDEVHDR free field.  Consists of a 4 byte offset to the next free space (or
       zero for end of free space chain), and a 4 byte length of the free space (which length  includes  the  8  bytes	occupied  by  the  FREEBLK
       itself), followed by zero or more bytes of residual data.  Described by the first 8 bytes of the CCKD_FREEBLK struct; 8 bytes in size.

   TRKHDR
       Occurs once at the beginning of each track.  contains flag (one byte), CC (two bytes), and HH (two bytes) of the track.	When the flag byte
       = 0x00, TRKHDR is the same as the Home Address on real DASD.  Flag bits are described in hercules.h, and are of the format  nlllllcc  where
       n=1 for new track header format, lllll is used for track recovery purposes, and cc describes the track compression algorithm.  The compres-
       sion algorithms are: B'00' = uncompressed, B'01' = zlib, B'10' = bzip2, B'11' is currently invalid.  Data in TRKHDR is stored in big-endian
       byte order.  Described by the CKDDASD_TRKHDR struct; 5 bytes in size.

   COUNT field
       8  bytes,  containing  CC (two bytes), HH (two bytes), R (one byte), KL (one byte), and DL (two bytes).	CC is the (relative zero) cylinder
       number.	HH is the (relative zero) head number.	R is the (relative zero) record number on the track.  KL is the key length; if zero no key
       is  present.   DL  is  the  length  of the data record.	Data in the COUNT field is stored in big-endian byte order.  Described by the CKD-
       DASD_RECHDR struct; 8 bytes in size.

   KEY field
       if present, KL bytes of record key; immediately follows the COUNT field.  Byte order is not a factor for the KEY field; to the extent it is
       examined by Hercules code it is simply a byte stream.  Size varies.

   DATA field.
       if  present,  DL  bytes	of  record  data; immediately follows the KEY field for keyed record, else immediately follows the COUNT field for
       unkeyed records.  Byte order is not a factor for the DATA field; to the extent it is examined by Hercules code it is simply a byte  stream.
       Size varies.

GLOSSARY

   CKD
       Count, Key, Data - contents of an track.  Also refers to the Hercules uncompressed DASD image file.

   CCKD
       Compressed Count, Key, Data - compressed contents of a track.  Also refers to the Hercules compressed DASD image file.

   DASD
       Direct Access Storage Device - term the IBM mainframe world uses to refer to hard drives.

   EOT
       End Of Track - indicated by 8X'FF' in the COUNT field.

SEE ALSO

       http://www.hercules-390.org/ the Hercules emulator homepage.

       http://www.hercules-390.org/cckddasd.html which describes
	      the Hercules CCKD DASD facility.

       http://www.hercules-390.org/hercconf.html which describes
	      the Hercules configuration file.

HISTORY

       2003-02-07 originally written by James M. Morrison

								    2003-02-03								   cckd(4)