/* $NetBSD: README.md_defs,v 1.8 2023/01/06 15:05:52 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 overridden / 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.

MD_MAY_SWAP_TO		may be undefined

used  like:

	bool MD_MAY_SWAP_TO(const char *disk_name)

returns true if the disk is usable as a swap device. Typical implementation
in utils.c:may_swap_if_not_sdmmc.

MD_SET_EXTRACT_FINALIZE	may be undefined

used like:

	int MD_SET_EXTRACT_FINALIZE(int update)

extracts any additional parts of the distribution. Returns an error code
if something fails.


HAVE_PLAIN_DISKLABEL_BOOT	may be undefined, only used on architectures
				that have MBR as primary with disklabel as
				secondary partitioning scheme (RAW_PART == 3)

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).


DISKLABEL_NO_ONDISK_VERIFY	usually undefined

If defined, do not verify the presence of on-disk disklabels before
offering the disklabel partitioning scheme. This allows ports to use
kernel translation for the disklabel ioctls (e.g. x68k uses Human68k
partitions this way).


HAVE_GPT_BOOT			defined if the architecture can boot from GPT

HAVE_EFI_BOOT			defined if the architecture may be able
				to boot from an EFI partition

NO_DISKLABEL_BOOT		defined if the architecture can NOT boot
				from a disklabel partitioned disk

MD_DISKLABEL_PART_INDEX_CHECK	usually undefined

				if defined evaluates to a boolean attribute
				which is passed a struct disklabel, an integer
				index and a const struct disk_part_info*.
				The result qualifies the given new partition
				to take the disklabel l_partition entry
				with the given index. Used for example
				in luna68k to move the FFSv1 boot partition
				(which would otherwise end up as partition 'a')
				to a partition past RAW_PART (so 'd' on luna68k)