]> git.ipfire.org Git - thirdparty/util-linux.git/commitdiff
libfdisk: add more comments
authorKarel Zak <kzak@redhat.com>
Thu, 16 Oct 2014 11:15:06 +0000 (13:15 +0200)
committerKarel Zak <kzak@redhat.com>
Thu, 16 Oct 2014 11:15:06 +0000 (13:15 +0200)
Signed-off-by: Karel Zak <kzak@redhat.com>
libfdisk/src/alignment.c
libfdisk/src/context.c
libfdisk/src/fdiskP.h
libfdisk/src/libfdisk.h

index 22be7a106c4cc2c8c817a93cdd4f40fd61d55bcf..09860703bf0502bd07e6eca49bb6d22fe0a82f92 100644 (file)
  * SECTION: alignment
  * @title: Align LBA
  * @short_description: function to align partitions and work with disk topology and geometry.
+ *
+ * The libfdisk aligns the end of the partitions to make it possible to align
+ * the next partition to the "grain" (see fdisk_get_grain()). The grain is
+ * usually 1MiB (or more for devices where optimal I/O is greater than 1MiB).
+ *
+ * It means that the library does not align strictly to physical sector size
+ * (or minimal or optimal I/O), but it uses greater granularity. It makes
+ * partition tables more portable. If you copy disk layout from 512-sector to
+ * 4K-sector device, all partitions are still aligned to physical sectors.
+ *
+ * This unified concept also makes partition tables more user friendly, all
+ * tables look same, LBA of the first partition is 2048 sectors everywhere, etc.
+ *
+ * It's recommended to not change any alignment or device properties. All is
+ * initialized by default by fdisk_assign_device().
+ *
+ * Note that terminology used by libfdisk is: 
+ *   - device properties: I/O limits (topology), geometry, sector size, ...
+ *   - alignment: first, last LBA, grain, ...
+ *
+ * The alignment setting may be modified by disk label driver.
  */
 
 /*
- * Alignment according to logical granulity (usually 1MiB)
+ * Alignment according to logical granularity (usually 1MiB)
  */
 static int lba_is_aligned(struct fdisk_context *cxt, sector_t lba)
 {
@@ -44,6 +65,10 @@ static int lba_is_phy_aligned(struct fdisk_context *cxt, sector_t lba)
  * @lba: address to align
  * @direction: FDISK_ALIGN_{UP,DOWN,NEAREST}
  *
+ * This function aligns @lba to the "grain" (see fdisk_get_grain()). If the
+ * device uses alignment offset then the result is moved according the offset
+ * to be on the physical boundary.
+ *
  * Returns: alignment LBA.
  */
 sector_t fdisk_align_lba(struct fdisk_context *cxt, sector_t lba, int direction)
@@ -132,7 +157,7 @@ sector_t fdisk_align_lba_in_range(struct fdisk_context *cxt,
  * @cxt: context
  * @lba: LBA to check
  *
- * Check if the @lba is aligned.
+ * Check if the @lba is aligned to physical sector boundary.
  *
  * Returns: 1 if aligned.
  */
@@ -168,8 +193,12 @@ static void recount_geometry(struct fdisk_context *cxt)
  * @heads: user specified heads
  * @sectors: user specified sectors
  *
- * Overrides autodiscovery and apply user specified geometry. The function
- * fdisk_reset_device_properties() restores the original setting.
+ * Overrides auto-discovery. The function fdisk_reset_device_properties() 
+ * restores the original setting.
+ *
+ * The difference between fdisk_override_geometry() and fdisk_save_user_geometry()
+ * is that saved user geometry is persistent setting and it's applied always 
+ * when device is assigned to the context or device properties are reseted.
  *
  * Returns: 0 on success, < 0 on error.
  */
@@ -209,6 +238,9 @@ int fdisk_override_geometry(struct fdisk_context *cxt,
  *
  * Save user defined geometry to use it for partitioning.
  *
+ * The user properties are applied by fdisk_assign_device() or 
+ * fdisk_reset_device_properties().
+
  * Returns: <0 on error, 0 on success.
  */
 int fdisk_save_user_geometry(struct fdisk_context *cxt,
@@ -242,6 +274,9 @@ int fdisk_save_user_geometry(struct fdisk_context *cxt,
  *
  * Save user defined sector sizes to use it for partitioning.
  *
+ * The user properties are applied by fdisk_assign_device() or 
+ * fdisk_reset_device_properties().
+ *
  * Returns: <0 on error, 0 on success.
  */
 int fdisk_save_user_sector_size(struct fdisk_context *cxt,
@@ -330,6 +365,20 @@ void fdisk_zeroize_device_properties(struct fdisk_context *cxt)
        memset(&cxt->geom, 0, sizeof(struct fdisk_geometry));
 }
 
+/**
+ * fdisk_reset_device_properties:
+ * @cxt: context
+ *
+ * Resets and discovery topology (I/O limits), geometry, re-read the first
+ * rector on the device if necessary and apply user device setting (geometry
+ * and sector size), then initialize alignment according to label driver (see
+ * fdisk_reset_alignment()).
+ *
+ * You don't have to use this function by default, fdisk_assign_device() is
+ * smart enough to initialize all necessary setting.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_reset_device_properties(struct fdisk_context *cxt)
 {
        int rc;
@@ -490,12 +539,6 @@ static sector_t topology_get_first_lba(struct fdisk_context *cxt)
        return res;
 }
 
-/*
- * The LBA of the first partition is based on the device geometry and topology.
- * This offset is generic generic (and recommended) for all labels.
- *
- * Returns: 0 on error or number of bytes.
- */
 static unsigned long topology_get_grain(struct fdisk_context *cxt)
 {
        unsigned long res;
@@ -523,7 +566,8 @@ static unsigned long topology_get_grain(struct fdisk_context *cxt)
  * fdisk_reset_alignment:
  * @cxt: fdisk context
  *
- * Resets alignment setting to the default or label specific values.
+ * Resets alignment setting to the default and label specific values. This
+ * function does not change device properties (I/O limits, geometry etc.).
  *
  * Returns: 0 on success, < 0 in case of error.
  */
@@ -569,7 +613,9 @@ sector_t fdisk_cround(struct fdisk_context *cxt, sector_t num)
  * fdisk_reread_partition_table:
  * @cxt: context
  *
- * Force *system kernel* to re-read partition table.
+ * Force *kernel* to re-read partition table on block devices.
+ *
+ * Returns: 0 on success, < 0 in case of error.
  */
 int fdisk_reread_partition_table(struct fdisk_context *cxt)
 {
index 2bef8e34752af54124878af52ed2b7d5624484f4..5385baaae7861546ecc1f1349439016ded7a501d 100644 (file)
  * @title: libfdisk handler
  * @short_description: stores infor about device, labels etc.
  *
- * Partitioning data:
+ * The library distinguish between three types of partitioning objects.
  *
  * on-disk data
- *    The libfdisk reads PT when you assign device to the context, the
- *    function fdisk_write_disklabel() modify on-disk data.
+ *    - disk label specific
+ *    - probed and read  by disklabel drivers when assign device to the context
+ *      or when switch to another disk label type
+ *    - only fdisk_write_disklabel() modify on-disk data
  *
  * in-memory data
- *    All data are label specific, but usually stored in the first sector
- *    which is cached in memory and shared between all label drivers (see
- *    labelsection for more details). All label operations are based on
- *    in-memory data.
+ *    - generic data and disklabel specific data stored in struct fdisk_label
+ *    - all partitioning operations are based on in-memory data only
  *
  * struct fdisk_partition
- *    The struct provides abstraction to present partitions to users (for
- *    example to generate human readable info about PT) and it's also unified
- *    way how to define partition template that can be used by label driver to
- *    create a new partition. It's necessary to understand the struct
- *    fdisk_partition is always completely independent object and any change to
- *    the object has no effect to in-memory (or on-disk) label data.
+ *    - provides abstraction to present partitions to users
+ *    - fdisk_partition is possible to gather to fdisk_table container
+ *    - used as unified template for new partitions
+ *    - the struct fdisk_partition is always completely independent object and
+ *      any change to the object has no effect to in-memory (or on-disk) label data
  */
 
 /**
@@ -183,7 +182,7 @@ struct fdisk_context *fdisk_new_nested_context(struct fdisk_context *parent,
  * fdisk_ref_context:
  * @cxt: context pointer
  *
- * Incremparts reference counter.
+ * Increments reference counter.
  */
 void fdisk_ref_context(struct fdisk_context *cxt)
 {
@@ -284,22 +283,6 @@ int __fdisk_switch_label(struct fdisk_context *cxt, struct fdisk_label *lb)
        return 0;
 }
 
-/**
- * fdisk_switch_label:
- * @cxt: context
- * @name: label name (e.g. "gpt")
- *
- * Forces libfdisk to use the label driver. It's usually bad idea to use this
- * function, it's better to use fdisk_create_disklabel().
- *
- *
- * Returns: 0 on succes, <0 in case of error.
- */
-int fdisk_switch_label(struct fdisk_context *cxt, const char *name)
-{
-       return __fdisk_switch_label(cxt, fdisk_get_label(cxt, name));
-}
-
 /**
  * fdisk_has_label:
  * @cxt: fdisk context
@@ -315,6 +298,36 @@ int fdisk_has_label(struct fdisk_context *cxt)
  * fdisk_get_npartitions:
  * @cxt: context
  *
+ * The maximal number of the partitions depends on disklabel and does not
+ * have to describe the real limit of PT.
+ *
+ * For example the limit for MBR without extend partition is 4, with extended
+ * partition it's unlimited (so the function returns the current number of all
+ * partitions in this case).
+ *
+ * And for example for GPT it depends on space allocated on disk for array of
+ * entry records (usually 128).
+ *
+ * It's fine to use fdisk_get_npartitions() in loops, but don't forget that
+ * partition may be unused (see fdisk_is_partition_used()).
+ *
+ * <informalexample>
+ *   <programlisting>
+ *     struct fdisk_partition *pa = NULL;
+ *     size_t i, nmax = fdisk_get_npartitions(cxt);
+ *
+ *     for (i = 0; i < nmax; i++) {
+ *             if (!fdisk_is_partition_used(cxt, i))
+ *                     continue;
+ *             ... do something ...
+ *     }
+ *   </programlisting>
+ * </informalexample>
+ *
+ * Note that the recommended way to list partitions is to use
+ * fdisk_get_partitions() and struct fdisk_table than ask disk driver for each
+ * individual partitions.
+ *
  * Returns: maximal number of partitions for the current label.
  */
 size_t fdisk_get_npartitions(struct fdisk_context *cxt)
@@ -529,6 +542,8 @@ fail:
  *
  * Close device and call fsync(). If the @cxt is nested context than the
  * request is redirected to the parent.
+ *
+ * Returns: 0 on success, < 0 on error.
  */
 int fdisk_deassign_device(struct fdisk_context *cxt, int nosync)
 {
@@ -620,7 +635,7 @@ void fdisk_unref_context(struct fdisk_context *cxt)
  * @ask_cb: callback
  * @data: callback data
  *
- * Set callbacks for dialog driven partitioning and library warnings/errors.
+ * Set callback for dialog driven partitioning and library warnings/errors.
  *
  * Returns: 0 on success, < 0 on error.
  */
@@ -776,7 +791,7 @@ unsigned int fdisk_get_units_per_sector(struct fdisk_context *cxt)
  * anyway libfdisk never returns zero. If the optimal I/O size is not provided
  * then libfdisk returns minimal I/O size or sector size.
  *
- * Returns: optimal I/O size
+ * Returns: optimal I/O size in bytes.
  */
 unsigned long fdisk_get_optimal_iosize(struct fdisk_context *cxt)
 {
@@ -788,7 +803,7 @@ unsigned long fdisk_get_optimal_iosize(struct fdisk_context *cxt)
  * fdisk_get_minimal_iosize:
  * @cxt: context
  *
- * Returns: minimal I/O size
+ * Returns: minimal I/O size in bytes
  */
 unsigned long fdisk_get_minimal_iosize(struct fdisk_context *cxt)
 {
@@ -800,7 +815,7 @@ unsigned long fdisk_get_minimal_iosize(struct fdisk_context *cxt)
  * fdisk_get_physector_size:
  * @cxt: context
  *
- * Returns: physical sector size
+ * Returns: physical sector size in bytes
  */
 unsigned long fdisk_get_physector_size(struct fdisk_context *cxt)
 {
@@ -812,7 +827,7 @@ unsigned long fdisk_get_physector_size(struct fdisk_context *cxt)
  * fdisk_get_sector_size:
  * @cxt: context
  *
- * Returns: sector size
+ * Returns: logical sector size in bytes
  */
 unsigned long fdisk_get_sector_size(struct fdisk_context *cxt)
 {
@@ -824,7 +839,11 @@ unsigned long fdisk_get_sector_size(struct fdisk_context *cxt)
  * fdisk_get_alignment_offset
  * @cxt: context
  *
- * Returns: alignment offset (used by 4K disks for backward compatibility with DOS tools).
+ * The alignment offset is offset between logical and physical sectors. For
+ * backward compatibility the first logical sector on 4K disks does no have to
+ * start on the same place like physical sectors.
+ *
+ * Returns: alignment offset in bytes
  */
 unsigned long fdisk_get_alignment_offset(struct fdisk_context *cxt)
 {
@@ -836,7 +855,7 @@ unsigned long fdisk_get_alignment_offset(struct fdisk_context *cxt)
  * fdisk_get_grain_size:
  * @cxt: context
  *
- * Returns: usual grain used to align partitions
+ * Returns: grain in bytes used to align partitions (usually 1MiB)
  */
 unsigned long fdisk_get_grain_size(struct fdisk_context *cxt)
 {
@@ -859,13 +878,17 @@ sector_t fdisk_get_first_lba(struct fdisk_context *cxt)
 /**
  * fdisk_set_first_lba:
  * @cxt: fdisk context
- * @lba: first possible sector for data
+ * @lba: first possible logical sector for data
  *
  * It's strongly recommended to use the default library setting. The first LBA
  * is always reseted by fdisk_assign_device(), fdisk_override_geometry()
  * and fdisk_reset_alignment(). This is very low level function and library
  * does not check if your setting makes any sense.
  *
+ * This function is necessary only when you want to work with very unusual
+ * partition tables like GPT protective MBR or hybrid partition tables on
+ * bootable media where the first partition may start on very crazy offsets.
+ *
  * Returns: 0 on success, <0 on error.
  */
 sector_t fdisk_set_first_lba(struct fdisk_context *cxt, sector_t lba)
@@ -893,12 +916,16 @@ sector_t fdisk_get_last_lba(struct fdisk_context *cxt)
 /**
  * fdisk_set_last_lba:
  * @cxt: fdisk context
- * @lba: last possible sector
+ * @lba: last possible logical sector
  *
  * It's strongly recommended to use the default library setting. The last LBA
  * is always reseted by fdisk_assign_device(), fdisk_override_geometry() and
  * fdisk_reset_alignment().
  *
+ * The default is number of sectors on the device, but maybe modified by the
+ * current disklabel driver (for example GPT uses and of disk for backup
+ * header, so last_lba is smaller than total number of sectors).
+ *
  * Returns: 0 on success, <0 on error.
  */
 sector_t fdisk_set_last_lba(struct fdisk_context *cxt, sector_t lba)
@@ -916,7 +943,7 @@ sector_t fdisk_set_last_lba(struct fdisk_context *cxt, sector_t lba)
  * fdisk_get_nsectors:
  * @cxt: context
  *
- * Returns: size of the device in (real) sectors.
+ * Returns: size of the device in logical sectors.
  */
 sector_t fdisk_get_nsectors(struct fdisk_context *cxt)
 {
index b9955fafb1ce7216ffb6098aacaa898c9f25d286..759abf3c47e4a4eb407455c39b80f6b19680e0ac 100644 (file)
@@ -391,7 +391,6 @@ extern int fdisk_missing_geometry(struct fdisk_context *cxt);
 /* alignment.c */
 sector_t fdisk_scround(struct fdisk_context *cxt, sector_t num);
 sector_t fdisk_cround(struct fdisk_context *cxt, sector_t num);
-int fdisk_reset_device_properties(struct fdisk_context *cxt);
 
 extern int fdisk_discover_geometry(struct fdisk_context *cxt);
 extern int fdisk_discover_topology(struct fdisk_context *cxt);
index cb40ecf01e5746afaf11ada75dfc03fcd5ec41b5..359bd4acbfa70a6cf5aa6203e6bd4d48511b5b68 100644 (file)
@@ -89,7 +89,6 @@ size_t fdisk_get_npartitions(struct fdisk_context *cxt);
 struct fdisk_label *fdisk_get_label(struct fdisk_context *cxt, const char *name);
 int fdisk_next_label(struct fdisk_context *cxt, struct fdisk_label **lb);
 size_t fdisk_get_nlabels(struct fdisk_context *cxt);
-int fdisk_switch_label(struct fdisk_context *cxt, const char *name);
 
 int fdisk_has_label(struct fdisk_context *cxt);
 int fdisk_is_labeltype(struct fdisk_context *cxt, enum fdisk_labeltype l);
@@ -349,6 +348,7 @@ int fdisk_save_user_sector_size(struct fdisk_context *cxt,
                                unsigned int log);
 int fdisk_has_user_device_properties(struct fdisk_context *cxt);
 int fdisk_reset_alignment(struct fdisk_context *cxt);
+int fdisk_reset_device_properties(struct fdisk_context *cxt);
 int fdisk_reread_partition_table(struct fdisk_context *cxt);
 
 /* iter.c */