home *** CD-ROM | disk | FTP | other *** search
/ Emulator Universe CD / emulatoruniversecd1998.iso / CPC / Utils / DSKutil / XTI.DOC < prev    next >
Encoding:
Text File  |  1996-12-13  |  17.3 KB  |  454 lines
  1.                  Disk Image XTender - Help File
  2.                  ------------------------------
  3.                   Release 1.2b - December 1996
  4.  
  5.                     (c) 1996 Pierre Guerrier
  6.                          pg@masi.ibp.fr
  7.  
  8.                    DOS port by Ulrich Doewich
  9.                       cyrel@cybercube.com
  10.  
  11.                   Amiga port by Kevin Thacker
  12.               http://andercheran.aiind.upv.es/CPC
  13.  
  14.                   Macintosh port by Brice Rive
  15.                        brice@worldnet.fr
  16.  
  17.  
  18.  
  19. Contents:
  20. --------
  21.  
  22.   Introduction
  23.        (with legal stuff)
  24.   Setting up an executable
  25.   Usage of the program
  26.   Reference
  27.      Definitions of the formats
  28.  
  29.  
  30.  
  31. Introduction
  32. ------------
  33.  
  34. Disk Image XTender is a utility that turns disk images of various formats
  35. into the "extended disk image format" (edsk) as defined by K.E.W Thacker,
  36. M. Vieth, and U. Doewich. This format supports copy-protected images, avoids
  37. waste of space, and it is the new standard for recent emulators.
  38.  
  39. But it can also be used to create new images, merge single-sided images into
  40. double-sided images (and vice versa), and include standalone AMSDOS files
  41. into edsk image files.
  42.  
  43.  
  44. The recognized source formats are:
  45.  
  46. dsk : The plain disk image format defined by M. Vieth for his emulator CPCemu.
  47.       This is the ancestor of edsk and still the present "industry standard".
  48.       It will be turned to edsk, which results in a much smaller file for
  49.       some images with copy-protections.
  50.  
  51. edsk: It may seem useless, but edsk to edsk "conversion" is supported.
  52.       This is actually a "cleaning" of the file, that ensures that all track
  53.       marks inside the file are properly set, as required by some emulators.
  54.  
  55. cpd : The CPE image format, as defined by B. Schmidt, author of the CPE emulator.
  56.       Only the uncompressed format is supported. It is converted to edsk, which
  57.       is usually smaller. Little testing done.
  58.  
  59. dif : The Disk Image Format as defined by B. Rive for the purpose of RS422
  60.       transfers from CPC to Macintosh (see the CPCterm program) and also
  61.       used by his CPC++ emulator. dif is supported only by CPCterm and CPC++.
  62.       It is converted to edsk, which may be slightly larger. Image XTender
  63.       accepts versions 0 through 2 of dif. Extensive bug hunt for the conversion
  64.       of this very flexible format was performed by F. Herlem.
  65.  
  66. emu : The EmuCPC image format as defined by S. Tavenard, author of this emulator.
  67.       The definition used here has actually been inferred from observations by
  68.       KEW Thacker. No testing done.
  69.  
  70. ami : The Ami-CPC image format as defined by L. Deplanque for his emulator on
  71.       the Amiga. No testing done.
  72.  
  73. cpc : The !CPCEmu image format (version 4) as defined by A. Stroiczek for his
  74.       emulator on the Archimedes. No testing done.
  75.  
  76. ncpc: The format for the NO$CPC emulator by Martin Korth. Files have the .dsk
  77.       suffix under DOS, but it is not the "standard" dsk. The real specs are
  78.       unknown, so you may encounter some problems...
  79.  
  80.  
  81. The code could be expanded to support other formats. If you know of another one,
  82. send me the definition and I will try to include it. You can also try to write
  83. the code yourself, it is not a great programming challenge.
  84.  
  85. The source code is given so that you may recompile Image XTender on any platform.
  86. It is freeware, that is, it remains copyrighted by me. But you can redistribute
  87. it as long as you keep the package complete and unmodified. Bugs and proposals
  88. should be directed to me, so that I can maintain an "official" release of the
  89. program, instead of having an anarchic proliferation of variants.
  90.  
  91. The DOS port of Image XTender was done by Ulrich Doewich, and any DOS-specific
  92. bug should be reported to him. The Amiga port was done by Kevin Thacker, report
  93. to him for any Amiga-specific bug. A Mac port is in progress, by Brice Rive.
  94. All parts of the code specific to DOS are (c) Ulrich Doewich.
  95. All parts of the code specific to the Amiga are (c) Kevin Thacker.
  96. All parts of the code specific to the Macintosh are (c) Brice Rive.
  97.  
  98. The definitions of the formats remain copyrighted by their respective designers.
  99.  
  100. No guarantee is given that the program will work properly. You run it at your
  101. own risks.
  102.  
  103.  
  104. Setting up an executable
  105. ------------------------
  106.  
  107. Your first step before using xti should be to compile the C source code on your
  108. architecture. For that, you have to type: (typically, for a UNIX system)
  109.  
  110. >gcc xti_main.c -o xti
  111.  ^^^
  112. The GNU C Compiler (gcc) can be replaced by another compiler. The source code
  113. is independant of the word size and endian of your architecture.
  114. It has been tested on SPARC and POWER (RS/6000) architectures.
  115.  
  116. ** DOS Notes:
  117.  
  118. When compiling for DOS, you need to change one line at the beginning of xti.c:
  119.  
  120. #define MSDOS 0        -------->>>>>   #define MSDOS 1
  121.  
  122. This way, all file suffixes will be limited to 3 characters. All suffixes are
  123. shortened: wherever you see ".edsk", ".xdsk", ".ddsk" in the following sections,
  124. read ".edk", ".xdk", ".ddk".
  125.  
  126.  
  127. Usage of the program
  128. --------------------
  129.  
  130. ** The first shell syntax is:
  131.  
  132. xti [-format override] [-special] image-file
  133.  
  134. ...where the optional override should be any of:
  135.      dsk, edsk, dif, odif, emu, cpd, ami, cpc, ncpc.
  136. It is used to force the format of the source file if the "auto-guess" feature
  137. doesn't work properly (notably for images that need to be "cleaned"). The meaning
  138. should be obvious, except for odif, which denotes images in older versions of the
  139. dif format.
  140.  
  141.  
  142.  * The special tag is one of the following:
  143.  
  144.  -DE : Data Error Protection Trick.
  145.        With this flag, the side field of the image header has its top bit set.
  146.        This is an extension of the edsk format to handle some very special
  147.        copy protections, where "Data Error" marked sectors should yield random
  148.        data when read. Your emulator may not support this extension, and most
  149.        images with DE sectors must not be read randomly.
  150.        If your emulator does not support this, it may not be able to load an 
  151.        image with the flag set. But without this support, it will not be able to
  152.        emulate the copy protection either, so whatever flag you have, the game
  153.        on the image won't work.
  154.        However, for greater compatibility, xti will *clear* the flag if you
  155.        clean an edsk without specifying the -DE tag. This way, you can set it
  156.        on and off as you wish.
  157.  
  158.  -cut%d, where %d is decimal number, like: cut6215
  159.        This tag is involved in the processing of the 8k sector protections. Use
  160.        it to specify the maximal number of bytes in a sector. The default value
  161.        is 0x1800 bytes. This corresponds to a feature included in the edsk format.
  162.        8k protections were previously possible only in dif and dsk (the latter
  163.        leading to delirial file sizes). This option will have no effect on files
  164.        of the other formats, with cut sizes around 6k. It has no effect on edsk
  165.        cleaning either.
  166.  
  167.  
  168. The "file" should be a complete file name (no automatic suffix expansion).
  169. The result is a file with the .edsk suffix replacing the suffix (if any, otherwise,
  170. it is appended) of the source file. In case of conflict with an edsk source file
  171. being cleaned, the target has a .xdsk suffix.
  172.  
  173. The original file is not modified. In the case of dsk and edsk source files, any
  174. extra information (like, user preferences) can be stored safely in the end of the
  175. image header, this information will be preserved in the result file (provided that
  176. it is not overwritten by the new data in the edsk header, which can use up to 220
  177. bytes from the beginning of the file).
  178. One extra track of correct structure appended after the last regular track in edsk
  179. files will also be copied without any change, for the same purpose.
  180.  
  181. Note that before converting anything to edsk with xti, you should check that your
  182. emulator supports this format, otherwise it will not be able to read the resulting
  183. images. In this case, try to get a newer release, or try reverting to dsk with the
  184. -back option (this is not always possible).
  185.  
  186.  
  187.  
  188. ** The second syntax is:
  189.  
  190. xti -merge image-file1 image-file2
  191.  
  192. If this syntax is used, xti will attempt to merge the images 1 and 2.
  193. Both must be single-sided extended dsk images.
  194. Image 1 will be the upper/A side and image 2 will be the lower/B side.
  195. The resulting image has the name of the first image with a .ddsk suffix.
  196. In the case of a name conflict, xti refuses to proceed with the merger.
  197. The original images are not modified.
  198.  
  199.  
  200.  
  201. ** The third syntax is:
  202.  
  203. xti -es[side] image-file
  204.  
  205. Here, xti will (e)xtract a (s)ide of the image-file, which must be a two-side
  206. extended dsk image. The "side" is "1" or "2" to select the first/upper/A side
  207. or the second/lower/B side. The result file has a .xdsk suffix.
  208.  
  209.  
  210.  
  211. ** The fourth syntax is:
  212.  
  213. xti -incl image-file
  214.  
  215. Where image-file is an image created by the -newX option of xti, of either
  216. DATA or SYSTEM format.It must not be write protected.
  217. You will get this prompt:
  218.  
  219.  Include file ?
  220.  
  221. Then you type in the name of a file to include in the image.
  222. After it has been included, you are prompted to include another one, until
  223. either the disk image is full or you type . (dot) as the name of the file
  224. to include.
  225.  
  226. Files are renamed as they are included, to avoid conflits with existing files
  227. and to fit in the AMSDOS format. The Includer tells you the name under which
  228. your file is included.
  229.  
  230.  
  231.  
  232. ** The fifth syntax is:
  233.  
  234. xti [format directive] image-file
  235.  
  236. where the format directive can be: -newD, -newS, -newI.
  237. This is for the creation of a new image file.
  238. In this case, the specified name is not that of a source file, but rather
  239. the name of a new file to be created from scratch, "formatted" in the usual
  240. CPC formats: DATA, SYSTEM/VENDOR, IBM. The new file is always single sided.
  241.  
  242.  
  243.  
  244. ** The sixth syntax is:
  245.  
  246. xti -back image-file
  247.  
  248. Here, xti will do the opposite of its usual job: it will try to revert the
  249. image (in edsk format) to the older dsk format. This is not always possible
  250. and you may get an error message telling you where the problem is.
  251.  
  252.  
  253.  
  254.  
  255. Definition of the formats
  256. -------------------------
  257.  
  258.  
  259. ------ Extended Disk Image Format, revision 5
  260.  
  261. DISK INFORMATION BLOCK
  262.     offset (hex)   description                                    bytes
  263.     00 - 21     "EXTENDED CPC DSK File\r\nDisk-Info\r\n"            34
  264.     22 - 2f     DSK creator (name of the utility)                   14
  265.     30          number of tracks                                    1
  266.     31          number of sides                                     1
  267.     32 - 33     unused                                              2
  268.     34 - xx     track size table                                1*tracks*sides
  269.  
  270. NOTES:  An extended DSK image is identified by the "EXTENDED" tag. The
  271.         track size at offset 32h is ignored for extended format DSK images.
  272.         The track size table contains the size of the tracks, in 256 byte chunks,
  273.         including track headers. Track data starts at offset 100h.
  274.         Zero-sized tracks are non-formatted and do not appear in the track data.
  275. SPECIAL:Image XTender uses the top bit of the side number byte as a flag for
  276.         the DE protection trick. Some emulators will not like that.
  277.         It also fills the old size field if all tracks are the same size.
  278.         Do not rely on this feature as it may be removed in the future.
  279.  
  280. Track information block: identical to original DSK definition, except for the
  281. sector information blocks. The last two bytes of these 8 byte blocks are now
  282. used to store the actual sector size in bytes (little endian word).
  283.  
  284.  
  285. ------ DSK Disk Image Format
  286.  
  287. File Header (hexa offsets):
  288. 00-21   MV-CPCEMU Disk-File\r\nDisk-Info\r\n
  289.         "MV-CPC" must be present, because it is used to identify the
  290.         file as a disk image.
  291. 22-2f   not used (0)
  292. 30      number of tracks in disk image (40,80,42...)
  293. 31      number of sides (1 or 2). track ordering is s0t0, s1t0 ... s0t39,s1t39
  294. 32-33   size of a track including &100 byte track info block (little endian)
  295.         All tracks must be the same size.
  296. 34-ff   not used (0)
  297.  
  298. Track Header:
  299. 00-0c   Track-Info\r\n
  300. 0d-0f   not used (0)
  301. 10      Track number (0 to number of tracks-1)
  302. 11      Side number (0 or 1)
  303. 12-13   not used (0)
  304. 14      BPS (bytes per sector) 2^(N+7)
  305.         This is used to calculate the sector data offset from the
  306.         Track Information Block.
  307. 15      SPT (sectors per track)
  308. 16      GAP#3 (used in formatting, &4e)
  309. 17      Filler Byte (byte used to fill sectors, &e5)
  310. 18-&ff  sector info list
  311. &100-tracksize : sector data
  312.  
  313. Sector info (for each sector)
  314. 0       track number (C)
  315. 1       head number (H)
  316. 2       sector id number (R)
  317. 3       sector size (N)
  318. 4       FDC Status register 1
  319. 5       FDC Status register 2
  320. 6       not used (0)
  321. 7       not used (0)
  322.  
  323.  
  324. ------ DIF Disk Image Format, revision 2
  325.  
  326.  The disk image file is made up of a 8192 bytes header that contains
  327.  disk, tracks, and sectors descriptions, followed by the sectors data.
  328.  The sectors data are clipped to at most 8192 bytes per sector.
  329.  
  330. Header format:
  331.  Byte 0:  Format Version (currently Version 2)
  332.  Byte 1:  number of tracks (single sided)
  333.  
  334.  Track descriptions:
  335.   Byte 0:  number of sectors
  336.  
  337.   Sector descriptions:
  338.    Byte 0:  Track ID
  339.    Byte 1:  Head ID
  340.    Byte 2:  Sector ID
  341.    Byte 3:  Sector Size (0=128, 1=256, 2=512, ...)
  342.    Byte 4:  Status register 0 (after a read)
  343.    Byte 5:  Status register 1 (after a read)
  344.    Byte 6:  Status register 2 (after a read)
  345.       Bit 8 is used as a flag indicating if the sector
  346.       is compressed (same value all over the sector).
  347.    Byte 7:  Value for a compressed sector.   
  348.    
  349.  Note: If a sector is compressed, its data wont show in the sectors data
  350.  section of the image file.
  351.  
  352.  In versions 0 and 1, the header is only 2048 bytes, and each sector has only
  353.  CHRN data (4 bytes). There is no STs and no compression. Sectors are still
  354.  clipped to 8k. Values of STs must be computed from those of CHRN.
  355.  In any case, there is no limitation on the sizes and structures of the tracks
  356.  and almost all copy protections can be handled with dif images.
  357.  
  358.  
  359. ------ EmuCPC Image Format
  360.  
  361. File Header (decimal offsets):
  362. 0..3            "CPCD"
  363.                 Used to identify this file as a EmuCPC disk image. This
  364.                 must be present
  365. 4..7            revision ?
  366. 8..11           reserved ?
  367. 12..15          Size of data in Image (excluding this header). Big Endian Long.
  368.                 EmuCPC disk images always have 40 tracks. So the size gives the
  369.                 number of sides. Order is s0t0...s0t39, s1t0...s1t39.
  370.  
  371. Then for each track:
  372. 0 .. 207        26 Sector entrys (described below)
  373. 208..4815       Sector data
  374.  
  375. Each sector entry is 8 bytes and has the form:
  376. 0             Sector ID (R value from READ ID command of FDC)
  377. 1             Sector size (N value from READ ID command of FDC)
  378.                 0=128 bytes, 1=256 bytes, 2=512 bytes.
  379.                 If this value is >5 then this means the sector doesnt
  380.                 exist.
  381. 2..3           16 bit sector CRC checksum (big endian)
  382.  
  383. 4..7           Offset for sector data within track block (big endian long)
  384.                 (offset 0 is the location of the first sector data and
  385.                 is directly after the header at offset 208 from the track)
  386.  
  387.  
  388. ------ Ami-CPC Image Format
  389.  
  390. 42 tracks of 9 sectors and for each sector:
  391.    - 4 bytes header (C,H,N,R - care for order !!)
  392.    - 512 bytes of sector data (fixed size)
  393.  Total sector size: 516 bytes
  394.  Total track size: 4644 bytes
  395.  Total image size: 195048 bytes
  396.  
  397.  
  398. ------ CPD Image Format, uncompressed
  399.  
  400. File header (decimal offsets)
  401. 0-7             "NORMDISK"
  402.                 This is used to identify the image as uncompressed CPE disk image.
  403. 8               Number of tracks in disk image (single sided)
  404. 9...            Each track data in turn. (Track 0, Track 1, Track 2...)
  405.  
  406. Track Data
  407. 0 .. 65         Sector IDs
  408. 66.. 131        Sector sizes
  409. 132..5251       Sector data
  410.  
  411. Sector IDs: for each sector (16 max, list is &FF-terminated)
  412. 1               ID (R, eg &C1, &C2...)
  413. Sector sizes: for each sector,  in the same order as the sector IDs.
  414. 1               Size (N eg 2->512 bytes)
  415.  
  416. Sector sizes:
  417. At offset 66 the sector sizes (in bytes, little endian longs) start.
  418. They are
  419.  
  420.  
  421. ------ !CPCemu Image Format, V4
  422.  
  423. File header: 128 bytes
  424. 0..15     "CPC-Emulator0.50"
  425. 16..31    "DiskImageV4" (padded with \0s)
  426. 32..47    "xxTracks" (where "xx" is the textual number of tracks)
  427. 48..63    "DoubleSided" (don't know if "SingleSided" exists)
  428. 64..127   reserved (zero)
  429.  
  430. For each track: side 0 then side 1
  431.  For each side: 6144 bytes of concatenated sectors, padded with 0s
  432.   For each sector:
  433.      0..3  "INDX" for first sector, or \0s
  434.      4..7  "IDFD"
  435.      8      C
  436.      9      H
  437.      10     R
  438.      11     N
  439.      12..27 reserved (zero)
  440.      28..31 "DATA"
  441.      32..   Sector Data (variable length)
  442.  
  443.  
  444. ------ NO$CPC Image format (assumed)
  445.  
  446. File Header: 2 bytes
  447. 0      0 (revision, binary flags ?)
  448. 1      ID of first sector on a track (&C1 for DATA format)
  449. Followed by sector data (concatenated data for tracks and sectors,
  450.   in the logical order of standard AMSDOS formats: &C1, &C2, &C3 ...)
  451. There can be 40,41 or 42 tracks. In the case of 40 tracks, the file
  452. is 184322 bytes long. It seems that tracks must always have 9 sectors
  453. of length 512.
  454.