[src/trunk]: src/usr.sbin/sysinst Provide some documentation for macros / def...

[martin <martin%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/570991e146a9
branches:  trunk
changeset: 844364:570991e146a9
user:      martin <martin%NetBSD.org@localhost>
date:      Wed Aug 14 12:49:37 2019 +0000

description:
Provide some documentation for macros / defines used in the machine
dependent backend parts of sysinst.

diffstat:

 usr.sbin/sysinst/README.md_defs |  85 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 85 insertions(+), 0 deletions(-)

diffs (89 lines):

diff -r 1a22e5a2e9a2 -r 570991e146a9 usr.sbin/sysinst/README.md_defs
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/usr.sbin/sysinst/README.md_defs   Wed Aug 14 12:49:37 2019 +0000
@@ -0,0 +1,85 @@
+/* $NetBSD: README.md_defs,v 1.1 2019/08/14 12:49:37 martin Exp $ */
+
+The following is trying to document the most important machine dependent
+defines used in the sysinst code.
+
+
+If HAVE_GPT is true, the MD code may limit the space used for the
+GPT at the beginning of the disk to allow e.g. a bootloader
+being added after it (see evbarm on allwinner SoCs, u-boot is
+copied at 8k into the image).
+
+/* Size limit for the initial GPT part, in bytes */
+#define        MD_GPT_INITIAL_SIZE             (8*1024)
+
+
+The default installation description is created as a static array using
+lots of conditionals. It may be overriden / replaced in the MD code
+(see below), an example for that is arch/i386/md.c when we have been
+booted from UEFI firmware.
+
+Name           Value / example         Description
+PART_BOOT      (8*MEG) (undefined)     if defined, a boot partition
+                                       of this size (in bytes, rounded)
+                                       will be part of the default partition
+                                       suggestions. Must be compile time
+                                       const! Use MD_PART_DEFAULTS if
+                                       runtime adjustment is needed.
+PART_BOOT_MOUNT        "/boot" (undefined)     Add boot partition to fstab for
+                                       this mount point
+PART_BOOT_TYPE FS_BSDFS                Kind of filesystem used
+PART_BOOT_SUBT MBR_PTYPE_FAT12         File system specific sub type
+
+
+The boot partition is always inserted at the front of the suggested default
+partitions, to cope with firmwares that may not be able to load from the
+whole disk.
+
+If multiple boot partitions are required (see ofppc, where various schemes
+are supported, depending on exact model), the variables above can all be
+repeated with _BOOT1_ or _BOOT2_ name instead of _BOOT_.
+
+
+ATTENTION:
+       PART_BOOT       is in BYTE (not MB), while most other sizes
+                       (DEFROOTSIZE, DEFSWAP, ...) are in MB!
+
+
+The following macros provide optional MD hooks:
+
+MD_PART_DEFAULTS       may be undefined
+
+used like:
+
+       void MD_PART_DEFAULTS(struct pm_dev*, struct part_usage_info*,
+           size_t num_usage_infos),
+
+Called before any of the partition usage defaults is ever used, can be used
+to adjust e.g. partition sizes to actual system requirements (align boot
+partition with cylindersize), or (since it is a macro and all params are
+by references) to completely swap the defaults (e.g. EFI vs. biosboot).
+If swapping, make sure allocation and num_usage_infos stays consistent,
+old allocation is done by calloc(3), use free(3) to release.
+
+
+MD_NEED_BOOTBLOCK      may be undefined
+
+used like:
+
+       bool MD_NEED_BOOTBLOCK(struct install_partition_desc *install)
+
+returns true if this setup needs boot blocks. Used for example on x86
+when UEFI installs do not need any bootblocks, but BIOS ones do.
+
+
+HAVE_PLAIN_DISKLABEL_BOOT      may be undefined, only used on architectures
+                               that have MBR as primary with disklabel as
+                               secondary partitioning scheme (RAW_PART != 2)
+
+used like:
+
+       bool HAVE_PLAIN_DISKLABEL_BOOT(const char *disk)
+
+returns true if the disk could be made bootable with only a disklabel
+(and no MBR).
+