-*- mode: indented-text -*-

$Id: README,v 1.4 1997/08/22 13:00:23 rnhodek Exp $

1) Partitioning Formats on the Atari
====================================

1.1) The Stone Age: The Original AHDI Format
--------------------------------------------

The original partitioning format for the Atari was introduced with
AHDI 1.0. In the root sector of the disk (sector 0), there is a table
with 4 slots for partition entries (see figure 1). These slots will be
called "primary partition entries" and the corresponding partitions
"primary partitions".

  Each of these slots can be used or not at will.[1] Thus, this format
allows max. 4 partitions, which can have in turn max. 16 MByte due to
limitations of the GEMDOS. All together, the whole disk is limited to
64 MByte.


 +-----------------+
 | primary entry 1 |---+
 +-----------------+   |
 | primary entry 2 |---+------------+
 +-----------------+   |    		|
 | primary entry 3 |---+------------+-------------------+
 +-----------------+   |			|					|
 | primary entry 4 |---+------------+-------------------+----------------+
 +-----------------+   |			|			    	|				 |
					   V			V			    	V				 V
      			  +----------+--------------+------------------------+-------+
      			  |          |              |                        |       |
      			  |  part. 1 |    part. 2   |        part. 3         | part.4|
      			  |          |              |                        |       |
      			  +----------+--------------+------------------------+-------+

			     Figure 1: Original AHDI Partitioning Format


  Each of the partition entries contains these fields:

 - A flag whether the entry is valid.

 - A flag whether the partition is bootable. If more than one
   partitions is marked bootable, AHDI would pick the first of these
   entries. ("Bootable" here means that the partition's first sector
   contains boot code that can be loaded and started by the root
   sector.)

 - The start sector of the disk (as an absolute sector number; this
   can also be seen as relative to the root sector, because the latter
   always has sector number 0).

 - The size of the partition in sectors.

 - A partition ID. This is a combination of three uppercase letters[2]
   that gives a hint what the partition is used for. Originally, there
   were only "GEM" partitions, i.e. partitions for GEMDOS with GEMDOS
   filesystems. More IDs were introduced later, see below.

-------

  [1] Also, there is no restriction that the partition data have to be
in the same order as the entries in the root sector. But this is
seldom done, because there are no advantages from this if creating a
partitioning from scratch and it just may be confusing. Nevertheless,
fdisk allows you to generate such things, and they can be useful if
editing and existing layout.

  [2] I don't see where the uppercase condition is defined, but I've
never seen something else. It's probably safe to use lowercase letters
and non-letter characters, but nothing will recognize such partitions :-)


1.2) Unlimited Number of Partitions: AHDI 3.0 format
----------------------------------------------------

Due to its limitation to 64 MByte, the original definition soon has
reached its limits. With the introduction of AHDI version 3.0, Atari
extended the partitioning format to allow for arbitrarily much
partitions. The key concept for this are the "extended partitions":
These are special partitions with ID "XGM" (see above for a definition
of the ID) that serve as a container for other partitions. There may
be only one extended partition and it must not occupy the first
primary entry.[3]


 +-----------------+
 | primary entry 1 |---+
 +-----------------+   |
 | primary entry 2 |---+--------+
 +-----------------+   |    	|
 | primary entry 3 |---+--------+----------+
 +-----------------+   |		|    	   |
 | primary entry 4 |---+--------+----------+----------------------+
 +-----------------+   |		|    	   |	    	    	  |
				       V    	V    	   V	    	    	  V
      			  +------+-----------+------------+--------------------------+
      			  |      |           |            |       extended part.     |
                  |part.1|  part. 2  |  part. 3   +-----+------+------+------+
      			  |      |           |            |sp#1 | sp#2 | sp#3 | ...  |
      			  +------+-----------+------------+-----+------+------+------+
													^
													subpartitions

		     Figure 2: AHDI 3.0 Format with Extended Partition


  The extended partition can contain as many so-called "subpartitions"
as you like (see figure 2). This is achieved by organizing the
subpartitions as a linked list and not as a table. For each
subpartition, there is an auxiliary root sector (often also called
secondary root sector), looking much like the real root sector. The
difference is that only two of the four entries may be used [4], one
of which must be a "real" data partition and the other is either
another "XGM" entry or empty. If it is "XGM", it points to the next
auxiliary root sector (see figure 3). This repeats until the second
entry is marked invalid, which ends the linked list.

  Subpartitions of an XGM partition are usually not bootable, because
it requires much and relatively complicated code in the boot loader to
find all the subpartitions. But basically it's possible, and some
drivers may also look for bootable partitions in an extended
partition. Anyway, I don't know one...[5]


                    pointer to                pointer to
                    next auxiliary            partition data
                    root sector
                           +--------------------+
                        +--| sec. root sec. #1  |--+
                        |  +--------------------+  |
                        |  |  subpartition #1   |<-+
                        |  |                    |
                        |  |                    |
                        +->+--------------------+
                        +--| sec. root sec. #2  |--+
                        |  +--------------------+  |
                        |  |  subpartition #2   |<-+
                        |  |                    |
                        |  |                    |
                        |  |                    |
                        |  |                    |
                        +->+--------------------+
                        +--| sec. root sec. #3  |--+
                        |  +--------------------+  |
                        |  |  subpartition #3   |<-+
                        |  |                    |
                        .  .          .         .
                        .  .          .         .
                        |  |                    |
                        +->+--------------------+
                      |----| sec. root sec. #n  |--+
                           +--------------------+  |
                           |  subpartition #n   |<-+
                           |                    |
                           +--------------------+

              Figure 3: Detail View of the Extended Partition

  If you know the partitioning format for PCs, you may see the close
analogies to the above. Basically, the two formats are the same, but
the terms and the contents of the partition entries differ:

    Atari Format             |  PC Format
 ----------------------------+-------------------------------
 Names:                      |
    root sector              |  master boot record
    (no own term)            |  primary partition
    extended partition       |  extended partition
    subpartition             |  logical partition
 ----------------------------+------------------------------
 Contents:                   |
                     sector numbering:
    logical block addresses  |  cylinder/head/sector notation
                             |
                     partition tagging:
    three-letter code        |  one-byte number
                             |

  Also, MS-DOS makes more differences between primary partitions and
logical partitions than TOS does. Here, you usually can't tell the
difference, execpt if you take a close look at the partition table.
But under M$-DOG, the primary partitions of *all* disks are put before
all logical partitions, so it *is* a difference whether a partition is
primary or logical. Under TOS, the extended partition mechanism is
just a data structure to implement more than 4 partitions, and the
user doesn't really have to care about it.

------

  [3] Alternative drivers (other than AHDI) may not have the
limitation to one extended partition. But two or more XGMs don't have
any advantage, since you can already put as many subpartitions in the
one extended partitions as you like. So it's advisable to stick with
only one extended partition. Since Atari explicitly forbid multiple
XGMs, fdisk doesn't allow you to create more than one.

  [4] And these two entries must be adjacent in the table. It is
not required (but usual) that the pointer to the data partition is
entry #0.

  [5] Atari LILO will be able to "boot" from extended partitions, but
this is something different: It always can load the kernel image from
everywhere on any disk. But if you want to install LILO in a
partition's boot sector (not the root sector), you're also limited to
what the code in the root sector can find, i.e. most probably only
primary partitions. One notable exception: For all drivers, it should
be possible to put boot code into the auxiliary root sector of the
first extended partition and mark the XGM entry in the root sector
bootable. But that boot code can't be a TOS hd driver, because those
usually expect to reside in the bootsector of a GEMDOS filesystem.


1.3) Other Partitioning Formats
-------------------------------

Beside the standard AHDI 3.0 format, Linux and Atari fdisk also
support the ICD format. For this reason, it will be mentioned here.
This format also addresses the problem that max. 4 partitions are much
to less. But the way to do so is totally different: In some other
location of the disk's root sector, 8 more slots for partition entries
are reserved (see figure 4). Together with the 4 standard slots, you
can thus have max. 12 partitions, which is usually enough. Extended
partitions are not allowed, i.e. a mixture of the two extensions to
the original format is forbidden.


                         +-----------------+
                         | ICD entry 1     |
                         +-----------------+
                         | ICD entry 2     |
                         +-----------------+
                         .    ...          .
                         .                 .
                         +-----------------+
                         | ICD entry 8     |
                         +-----------------+
                         .                 .
                         .                 .
                         +-----------------+
                         | primary entry 1 |
                         +-----------------+
                         | primary entry 2 |
                         +-----------------+
                         | primary entry 3 |
                         +-----------------+
                         | primary entry 4 |
                         +-----------------+

				Figure 4: The ICD Partitioning Format

  The main disadvantage of the ICD format, compared to AHDI 3.0
format, is that the number of partitions is still limited, even if the
limit is higher (12 vs. 4). If you want to have 13 partitions, you
loose... Also, space in the root sector is usually rare, because it
contains the boot loader code besides the partition table. And 512
byte are not really plenty. The ICD extension "wastes" another 8*12 =
96 bytes in the root sector.



2) Editing Partition Tables and Non-Standard Layouts
====================================================

Atari fdisk supports several specialities not supported by other
partitioning tools. The need for most of them stems from the fact that
fdisk also allows you to *edit* existing partition layouts, whereas
most other tools only create new layouts from scratch. Those force you
to backup all your data (which is a good idea anyway...) and newly
format the whole disk, also if you just want to make changes to a few
partitions. Atari fdisk doesn't have this restriction. It touches only
that data on disk that is has to touch.

2.1) Expert Mode
----------------

To give you maximum flexibility when editing a partition layout, Atari
fdisk allows you to do everything that is possible with the Atari
partition format, even if it's unusual. Also things are considered
"possible" if they're not explicitly forbidden and should be working
with most TOS hard disk drivers. But having the power to do everything
one likes can also be dangerous, can require knowledge that not
everyone has, and can be sometimes confusing. To keep the average user
from the full power that he probably doesn't need, fdisk implements
two modes of operation, non-expert mode and expert mode. In the
former, no knowledge about the partition format is required, expect
that you have to know what partitions are... In the latter, you can do
everything you want.

  Most Atari users are not used to the concepts of extended partitions
and related things, simply because the difference between primary and
extended partitions is not visible at the user level. Therefore, Atari
fdisk in non-expert mode tries to keep the user from the details of
extended partitions.

  To avoid several complications where deeper knowledge of the
partition format would be required, non-expert mode has some
restriction on how new partitions are created:

 - New partitions are always inserted into the existing table in
   "canonical ordering", i.e. partitions are numbered in the same
   order as they are located on disk. This alone already avoids many
   complex cases...

 - If it's not possible to create the partition with its canonical
   number, the creation simply fails. No options are offered how to
   fix the problem.

 - If the partition can be both, primary or extended, it will be an
   extended partition if and only if there are no extended partitions
   yet and already 3 slots in the root sector are allocated, or if the
   new partition is inside or adjacent to existing extended
   partitions.

  If a partition can't be created with the restrictions above, either
reorganize your current structure by deleting other partitions,
convert primary to extended partitions (or vice versa, in some cases),
or switch to expert mode.

  In expert mode, you first enter where the partition should be on
disk. Next, fdisk calculates which numbers would be possible for a
partition in that location. You can then choose one of these numbers,
and decide whether the partition should be primary or extended, if
both is possible. For extended partitions, you can also choose where
to put the auxiliary root sector, if a choice is possible.


2.2) Contents Status of Partitions
----------------------------------

Unlike other partitioning tools, and unlike fdisk for other partition
formats (e.g. PC), Atari fdisk maintains a "contents valid" status bit
for each partition. This flag signals to fdisk whether it can reuse a
sector of the partition as secondary root sector, if that should
become necessary for converting the partition from primary to
extended.

  All partitions found when fdisk started are considered "valid". This
needs not be the case in reality, but fdisk can't tell, and assuming
valid contents is the safer alternative... All partitions created by
fdisk in the same run are considered invalid. This is based on the
assumption that you don't play tricks and create a partition exactly
where you know a valid filesystem is. Also, if you do certain
operations on a partition which make its contents invalid (e.g.
changing size), the valid flag is cleared.

  You can change the contents status any time with the 'i' command:
Either if you know an existing partition contains junk, or if you did
the above mentioned trick and "re-created" a partition.


  The contents-valid flag is used by fdisk in some places to warn you
about operations that would make a partition's contents invalid (e.g.
changing partition size). It is also planned for the future to solve
problems when creating partitions by automatically converting between
primary and extended partitions. Since primary->extended conversions
make a partition one sector smaller, it makes the contents invalid,
too. With the help of the valid flag, fdisk can tell by itself whether
this is allowed.


2.3) Unordered Layouts
----------------------

If editing an existing layout, several anomalies can happen: First,
you could wish to insert the partition entry for a new partition
anywhere in between the existing entries, independent from how the
partition data is placed relative to other partitions. If creating a
layout from scratch, this doesn't happen, because the "canonical"
ordering of entries is the same as the order of the associated data.

  But I can't see any reason why such "unordered" layouts should cause
any problems. Any code that parses the partition table (TOS hard disk
drivers and non-TOS operating systems) would have to check explicitly
for this case and reject it, and I doubt they in fact do. (Linux of
course does not :-)

  In fdisk's expert mode, it's no problem at all to create such
unordered layouts. But in non-expert mode, fdisk automatically chooses
the partition number for new partitions so that the layout is ordered.
Of course, if the layout was already unordered before you started
fdisk, also non-expert mode won't change this...


2.4) Unordered Extended Partitions
----------------------------------

A special case of an unordered layout is when the extended partitions
inside the XGM area are also unordered. This is rarely done because it
seems complicated, but it isn't, IMHO :-)




2.5) XGM Area Overlapping Primary Partitions
--------------------------------------------

2.6) Detached Auxiliary Root Sectors
------------------------------------

2.7) Enforced Conditions
------------------------

 - only one XGM
 - XGM not in first slot
 - ars before part. data
 - ars of first ext. part. must be lowest-numbered sector of all ext.
   parts.


2.8) Problem When Splitting Partitions
--------------------------------------

Most problem for which you need expert mode to solve arise if you try
to split an existing partitions into two or even more. Since this is a
common case, I want to explain what happens and how to deal with it in
this section. It also repeats some of the thoughts above.

  If you delete an partition and want to create more smaller ones in
its place, bad problems can show up that have their roots in the
differences between primary and extended partitions. Thus, the
following only applies to AHDI format (with XGM), ICD format is not
affected (is basically has only primary slots).

  The problems are due to the auxiliary root sector needed for
extended partitions. Consider the following example: You had initially
four primary partitions and then delete the first of them. The layout
now looks like: (fdisk has moved the used entries one slot down)

  prim slot #0, part. #1: 100-199
  prim slot #1, part. #2: 200-299
  prim slot #2, part. #3: 300-399
  prim slot #3          : empty
  (disk size 400 sectors; sectors 1-99 unallocated)

Now you want to create two new partitions in place of the first.
There are several possibilities:

 1) The new partitions are given numbers at the end, and are made
    extended partitions. Result:

      prim slot #0, part. #1: 100-199
      prim slot #1, part. #2: 200-299
      prim slot #2, part. #3: 300-399
      prim slot #3          : XGM (1-99)
       extended #0, part. #4:   1- 49 (1 is aux. root sector)
       extended #1, part. #5:  50- 49 (50 is aux. root sector)

      First, this is an unordered layout, as mentioned before, but
    that is acceptable. Anyway, you may have preferred the new
    partitions to be number 1 and 2... Any other consecutive numbers,
    i.e. 2/3 or 3/4 are also no problem, because the XGM can be put in
    the appropriate slot. But 1/2 doesn't work, because the first slot
    may not be XGM.

      This problem appears only if the deleted partition was the
    first. But you also may have a problem if there are already
    extended partitions whose numbers aren't adjacent to those you
    want for the new partitions.

 2) To make the new partitions become number 1 and 2, fdisk would have
    to create an XGM at the end for the last two partitions, like:

      prim slot #0, part. #1:   1- 49
      prim slot #1, part. #2:  50- 99
      prim slot #2, part. #3: 100-199
      prim slot #3          : XGM (200-399)
       extended #0, part. #4: 200-299 (NO AUX ROOT SECTOR!!)
       extended #1, part. #5: 300-399 (NO AUX ROOT SECTOR!!)

      The problem now is that the last two partitions must be given a
    secondary root sector, for which there is no space. Their first
    sector already contains partition data, and thus cannot be used.
    Also, there is no free space before them. You loose :-(

      But, if fdisk knew that the contents of these partitions are
    invalid anyway (because they were freshly created before), or
    because you're not interested in their contents, it could cut off
    one sector at the start of each partition and turn it into an aux.
    root sector. Atari fdisk therefore has an "contents valid" status
    bit for each partition. (see section 2.2)

      For the future, it is planned that fdisk does such conversions
    automatically if it knows the contents are invalid. For now, you
    have to decide and convert manually.
    
 3) Elaborating on case 2, we could also assign unusual locations to
    the missing auxiliary root sectors, i.e. not immediately before
    the partition data:

      prim slot #0, part. #1:   1- 49
      prim slot #1, part. #2:  50- 97
      prim slot #2, part. #3: 100-199
      prim slot #3          : XGM (98-399)
       extended #0, part. #4: 200-299 (98 is aux. root sector)
       extended #1, part. #5: 300-399 (99 is aux. root sector)

      Here we avoided the XGM being in slot 0, but need overlapping
    (section 2.5) and detached auxiliary root sectors (section 2.6).
    This is possible, because the offset to the partition data is
    stored in the secondary root sector. It is usually 1, but nobody
    said it always must be 1. Any positive number is allowed. So we
    can "steal" two sectors from the region to be assigned to the
    second new partition (any free sectors before the data sectors are
    ok) to convert the partitions at 200 and 300 into extended
    partitions. This is always possible, since if you create a new
    partition, there is free space for it, from which the necessary
    sector can be taken. Nevertheless, a few limitations apply: Since
    the offset must be positive[6], the aux. root sector must be
    located before its data region.

There are also even more difficult cases. Consider, for instance, that
there are already extended partitions at the end:

  prim slot #0, part. #1:   1- 99
  prim slot #1, part. #2: 100-199
  prim slot #2, part. #3: 200-299
  prim slot #3          : XGM (300-399)
   extended #0, part. #4: 300-349 (300 is aux. root sector)
   extended #1, part. #5: 350-399 (350 is aux. root sector)

If now again the first partition is deleted and two partitions should
be created in its place. Now one of these can be put in the free
primary slot (becoming partition #1), but the other can not. Again,
there is the possibility the make an XGM entry into slot #0, but
besides that being disallowed, we'd have two XGMs them, which is also
illegal, according to the specifications.

A seemingly better solution is to make the existing XGM "overlap"
partitions 2 and 3:

  prim slot #0, part. #1:   1- 49
  prim slot #1, part. #2: 100-199
  prim slot #2, part. #3: 200-299
  prim slot #3          : XGM (50-399)
   extended #0, part. #4:  50- 99 (50 is aux. root sector)
   extended #1, part. #5: 300-349 (300 is aux. root sector)
   extended #2, part. #6: 350-399 (350 is aux. root sector)

This is non-standard, too, but shouldn't make problems like unordered
partitions: Programs that read the partition table usually don't check
for such overlappings, and thus should ignore it. Also, the data are
consistent, since no disk sector is assigned to two different
partitions. Only the XGM, which is only a logical container for its
subpartitions, but has no other meaning, is overlapping the primary
partitions.

------

  [6] It's not clearly specified whether the field is an signed or
unsigned integer, but this creates the possibility for different
programs to handle that differently. So you're on the safe side only
if you restrict to positive numbers of the signed format...