feat: add uefi and secure boot

Adds options to explicitly enable UEFI and Secure Boot (required UEFI).

Also, updates the descriptions for the documentation and moves the CoreCount right after CPUCount to maintain a logical order.

Ref: #58

Signed-off-by: Ryan Johnson <ryan@tenthirtyam.org>

.web-docs/components/builder/iso/README.md

@@ -572,53 +572,58 @@ provisioner](/packer/docs/provisioner/file).
 
 <!-- Code generated from the comments of the HWConfig struct in builder/vmware/common/hw_config.go; DO NOT EDIT MANUALLY -->
 
-- `cpus` (int) - The number of cpus to use when building the VM.
+- `firmware` (string) - The firmware type for the virtual machine.
+  Allowed values are `bios`, `efi`, and `efi-secure` (for secure boot).
+  Defaults to the recommended firmware type for the guest operating system.
 
-- `memory` (int) - The amount of memory to use when building the VM in megabytes.
+- `cpus` (int) - The number of virtual CPUs cores for the virtual machine.
 
-- `cores` (int) - The number of cores per socket to use when building the VM. This
-  corresponds to the cpuid.coresPerSocket option in the .vmx file.
+- `cores` (int) - The number of virtual CPU cores per socket for the virtual machine.
 
-- `network` (string) - This is the network type that the virtual machine will be created with.
-  This can be one of the generic values that map to a device such as
-  hostonly, nat, or bridged. If the network is not one of these values,
-  then it is assumed to be a VMware network device. (VMnet0..x)
+- `memory` (int) - The amount of memory for the virtual machine in MB.
 
-- `network_adapter_type` (string) - This is the ethernet adapter type the the virtual machine will be
-  created with. By default the `e1000` network adapter type will be used
-  by Packer. For more information, please consult [Choosing a network
-  adapter for your virtual
-  machine](https://kb.vmware.com/s/article/1001805) for desktop VMware
-  clients. For ESXi, refer to the proper ESXi documentation.
+- `network` (string) - The network which the virtual machine will connect for local desktop
+  hypervisors. Use the generic values that map to a device, such as
+  `hostonly`, `nat`, or `bridged`. Defaults to `nat`.
+
+  ~> **Note:** If not set to one of these generic values, then it is
+  assumed to be a network device (_e.g._, `VMnet0..x`).
+
+- `network_name` (string) - The network which the virtual machine will connect on a remote
+  hypervisor.
 
-- `network_name` (string) - The custom name of the network. Sets the vmx value "ethernet0.networkName"
+- `network_adapter_type` (string) - The virtual machine network card type. Recommended values are `e1000` and
+  `vmxnet3`. Defaults to `e1000`.
+
+  Refer to VMware product documentation for supported network adapter types
+  for the hypervisor and guest operating system.
 
-- `sound` (bool) - Specify whether to enable VMware's virtual soundcard device when
-  building the VM. Defaults to false.
+- `sound` (bool) - Enable virtual sound card device. Defaults to `false`.
 
-- `usb` (bool) - Enable VMware's USB bus when building the guest VM. Defaults to false.
-  To enable usage of the XHCI bus for USB 3 (5 Gbit/s), one can use the
-  vmx_data option to enable it by specifying true for the usb_xhci.present
-  property.
+- `usb` (bool) - Enable a the USB 2.0 controllers for the virtual machine.
+  Defaults to `false`.
+
+  ~> **Note:** To enable USB 3.0 controllers, set a `usb_xhci.present`
+  key to `true` in the `vmx_data` option.
 
-- `serial` (string) - This specifies a serial port to add to the VM. It has a format of
-  `Type:option1,option2,...`. The field `Type` can be one of the following
-  values: `FILE`, `DEVICE`, `PIPE`, `AUTO`, or `NONE`.
+- `serial` (string) - Add a serial port to the virtual machine. Use a format of
+  `Type:option1,option2,...`. Allowed values for the field `Type` include:
+  `FILE`, `DEVICE`, `PIPE`, `AUTO`, or `NONE`.
 
   * `FILE:path(,yield)` - Specifies the path to the local file to be used
     as the serial port.
 
     * `yield` (bool) - This is an optional boolean that specifies
-      whether the vm should yield the cpu when polling the port. By
-      default, the builder will assume this as `FALSE`.
+      whether the virtual machine should yield the CPU when polling the
+      port. By default, the builder will assume this as `FALSE`.
 
   * `DEVICE:path(,yield)` - Specifies the path to the local device to be
      used as the serial port. If `path` is empty, then default to the first
     serial port.
 
     * `yield` (bool) - This is an optional boolean that specifies
-      whether the vm should yield the cpu when polling the port. By
-      default, the builder will assume this as `FALSE`.
+      whether the virtual machine should yield the CPU when polling the
+      port. By default, the builder will assume this as `FALSE`.
 
   * `PIPE:path,endpoint,host(,yield)` - Specifies to use the named-pipe
     "path" as a serial port. This has a few options that determine how the
@@ -627,38 +632,38 @@ provisioner](/packer/docs/provisioner/file).
     * `endpoint` (string) - Chooses the type of the VM-end, which can be
       either a `client` or `server`.
 
-    * `host` (string)     - Chooses the type of the host-end, which can
-      be either `app` (application) or `vm` (another virtual-machine).
+    * `host` (string) - Chooses the type of the host-end, which can be
+      either `app` (application) or `vm` (another virtual-machine).
 
-    * `yield` (bool)      - This is an optional boolean that specifies
-      whether the vm should yield the cpu when polling the port. By
+    * `yield` (bool) - This is an optional boolean that specifies whether
+      the virtual machine should yield the CPU when polling the port. By
       default, the builder will assume this as `FALSE`.
 
   * `AUTO:(yield)` - Specifies to use auto-detection to determine the
-    serial port to use. This has one option to determine how the VM should
-    support the serial port.
+    serial port to use. This has one option to determine how the virtual
+    machine should support the serial port.
 
-    * `yield` (bool) - This is an optional boolean that specifies
-      whether the vm should yield the cpu when polling the port. By
+    * `yield` (bool) - This is an optional boolean that specifies whether
+      the virtual machine should yield the CPU when polling the port. By
       default, the builder will assume this as `FALSE`.
 
   * `NONE` - Specifies to not use a serial port. (default)
 
-- `parallel` (string) - This specifies a parallel port to add to the VM. It has the format of
-  `Type:option1,option2,...`. Type can be one of the following values:
+- `parallel` (string) - Add a parallel port to add to the virtual machine. Use a format of
+  `Type:option1,option2,...`. Allowed values for the field `Type` include:
   `FILE`, `DEVICE`, `AUTO`, or `NONE`.
 
-  * `FILE:path` 		- Specifies the path to the local file to be used
-    for the parallel port.
+  * `FILE:path` - Specifies the path to the local file to be used for the
+     parallel port.
 
-  * `DEVICE:path`	 	- Specifies the path to the local device to be used
-    for the parallel port.
+  * `DEVICE:path` - Specifies the path to the local device to be used for
+     the parallel port.
 
-  * `AUTO:direction`   - Specifies to use auto-detection to determine the
+  * `AUTO:direction` - Specifies to use auto-detection to determine the
     parallel port. Direction can be `BI` to specify bidirectional
     communication or `UNI` to specify unidirectional communication.
 
-  * `NONE` 			- Specifies to not use a parallel port. (default)
+  * `NONE` - Specifies to not use a parallel port. (default)
 
 <!-- End of code generated from the comments of the HWConfig struct in builder/vmware/common/hw_config.go; -->
 

builder/vmware/common/hw_config.go

@@ -9,59 +9,76 @@ import (
 	"fmt"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
 
 	"github.com/hashicorp/packer-plugin-sdk/template/interpolate"
 )
 
+// Set the firmware types for the virtual machine.
+const (
+	FirmwareTypeBios       = "bios"
+	FirmwareTypeUEFI       = "efi"
+	FirmwareTypeUEFISecure = "efi-secure"
+)
+
+// allowedFirmwareTypes is a list of allowed firmware types for the virtual
+// machine.
+var allowedFirmwareTypes = []string{FirmwareTypeBios, FirmwareTypeUEFI, FirmwareTypeUEFISecure}
+
 type HWConfig struct {
-	// The number of cpus to use when building the VM.
+	// The firmware type for the virtual machine.
+	// Allowed values are `bios`, `efi`, and `efi-secure` (for secure boot).
+	// Defaults to the recommended firmware type for the guest operating system.
+	Firmware string `mapstructure:"firmware" required:"false"`
+	// The number of virtual CPUs cores for the virtual machine.
 	CpuCount int `mapstructure:"cpus" required:"false"`
-	// The amount of memory to use when building the VM in megabytes.
-	MemorySize int `mapstructure:"memory" required:"false"`
-	// The number of cores per socket to use when building the VM. This
-	// corresponds to the cpuid.coresPerSocket option in the .vmx file.
+	// The number of virtual CPU cores per socket for the virtual machine.
 	CoreCount int `mapstructure:"cores" required:"false"`
-	// This is the network type that the virtual machine will be created with.
-	// This can be one of the generic values that map to a device such as
-	// hostonly, nat, or bridged. If the network is not one of these values,
-	// then it is assumed to be a VMware network device. (VMnet0..x)
+	// The amount of memory for the virtual machine in MB.
+	MemorySize int `mapstructure:"memory" required:"false"`
+	// The network which the virtual machine will connect for local desktop
+	// hypervisors. Use the generic values that map to a device, such as
+	// `hostonly`, `nat`, or `bridged`. Defaults to `nat`.
+	//
+	// ~> **Note:** If not set to one of these generic values, then it is
+	// assumed to be a network device (_e.g._, `VMnet0..x`).
 	Network string `mapstructure:"network" required:"false"`
-	// This is the ethernet adapter type the the virtual machine will be
-	// created with. By default the `e1000` network adapter type will be used
-	// by Packer. For more information, please consult [Choosing a network
-	// adapter for your virtual
-	// machine](https://kb.vmware.com/s/article/1001805) for desktop VMware
-	// clients. For ESXi, refer to the proper ESXi documentation.
-	NetworkAdapterType string `mapstructure:"network_adapter_type" required:"false"`
-	// The custom name of the network. Sets the vmx value "ethernet0.networkName"
+	// The network which the virtual machine will connect on a remote
+	// hypervisor.
 	NetworkName string `mapstructure:"network_name" required:"false"`
-	// Specify whether to enable VMware's virtual soundcard device when
-	// building the VM. Defaults to false.
+	// The virtual machine network card type. Recommended values are `e1000` and
+	// `vmxnet3`. Defaults to `e1000`.
+	//
+	// Refer to VMware product documentation for supported network adapter types
+	// for the hypervisor and guest operating system.
+	NetworkAdapterType string `mapstructure:"network_adapter_type" required:"false"`
+	// Enable virtual sound card device. Defaults to `false`.
 	Sound bool `mapstructure:"sound" required:"false"`
-	// Enable VMware's USB bus when building the guest VM. Defaults to false.
-	// To enable usage of the XHCI bus for USB 3 (5 Gbit/s), one can use the
-	// vmx_data option to enable it by specifying true for the usb_xhci.present
-	// property.
+	// Enable a the USB 2.0 controllers for the virtual machine.
+	// Defaults to `false`.
+	//
+	// ~> **Note:** To enable USB 3.0 controllers, set a `usb_xhci.present`
+	// key to `true` in the `vmx_data` option.
 	USB bool `mapstructure:"usb" required:"false"`
-	// This specifies a serial port to add to the VM. It has a format of
-	// `Type:option1,option2,...`. The field `Type` can be one of the following
-	// values: `FILE`, `DEVICE`, `PIPE`, `AUTO`, or `NONE`.
+	// Add a serial port to the virtual machine. Use a format of
+	// `Type:option1,option2,...`. Allowed values for the field `Type` include:
+	// `FILE`, `DEVICE`, `PIPE`, `AUTO`, or `NONE`.
 	//
 	// * `FILE:path(,yield)` - Specifies the path to the local file to be used
 	//   as the serial port.
 	//
 	//   * `yield` (bool) - This is an optional boolean that specifies
-	//     whether the vm should yield the cpu when polling the port. By
-	//     default, the builder will assume this as `FALSE`.
+	//     whether the virtual machine should yield the CPU when polling the
+	//     port. By default, the builder will assume this as `FALSE`.
 	//
 	// * `DEVICE:path(,yield)` - Specifies the path to the local device to be
 	//   used as the serial port. If `path` is empty, then default to the first
 	//   serial port.
 	//
 	//   * `yield` (bool) - This is an optional boolean that specifies
-	//     whether the vm should yield the cpu when polling the port. By
-	//     default, the builder will assume this as `FALSE`.
+	//     whether the virtual machine should yield the CPU when polling the
+	//     port. By default, the builder will assume this as `FALSE`.
 	//
 	// * `PIPE:path,endpoint,host(,yield)` - Specifies to use the named-pipe
 	//   "path" as a serial port. This has a few options that determine how the
@@ -70,57 +87,60 @@ type HWConfig struct {
 	//   * `endpoint` (string) - Chooses the type of the VM-end, which can be
 	//     either a `client` or `server`.
 	//
-	//   * `host` (string)     - Chooses the type of the host-end, which can
-	//     be either `app` (application) or `vm` (another virtual-machine).
+	//   * `host` (string) - Chooses the type of the host-end, which can be
+	//     either `app` (application) or `vm` (another virtual-machine).
 	//
-	//   * `yield` (bool)      - This is an optional boolean that specifies
-	//     whether the vm should yield the cpu when polling the port. By
+	//   * `yield` (bool) - This is an optional boolean that specifies whether
+	//     the virtual machine should yield the CPU when polling the port. By
 	//     default, the builder will assume this as `FALSE`.
 	//
 	// * `AUTO:(yield)` - Specifies to use auto-detection to determine the
-	//   serial port to use. This has one option to determine how the VM should
-	//   support the serial port.
+	//   serial port to use. This has one option to determine how the virtual
+	//   machine should support the serial port.
 	//
-	//   * `yield` (bool) - This is an optional boolean that specifies
-	//     whether the vm should yield the cpu when polling the port. By
+	//   * `yield` (bool) - This is an optional boolean that specifies whether
+	//     the virtual machine should yield the CPU when polling the port. By
 	//     default, the builder will assume this as `FALSE`.
 	//
 	// * `NONE` - Specifies to not use a serial port. (default)
-	//
 	Serial string `mapstructure:"serial" required:"false"`
-	// This specifies a parallel port to add to the VM. It has the format of
-	// `Type:option1,option2,...`. Type can be one of the following values:
+	// Add a parallel port to add to the virtual machine. Use a format of
+	// `Type:option1,option2,...`. Allowed values for the field `Type` include:
 	// `FILE`, `DEVICE`, `AUTO`, or `NONE`.
 	//
-	// * `FILE:path` 		- Specifies the path to the local file to be used
-	//   for the parallel port.
+	// * `FILE:path` - Specifies the path to the local file to be used for the
+	//    parallel port.
 	//
-	// * `DEVICE:path`	 	- Specifies the path to the local device to be used
-	//   for the parallel port.
+	// * `DEVICE:path` - Specifies the path to the local device to be used for
+	//    the parallel port.
 	//
-	// * `AUTO:direction`   - Specifies to use auto-detection to determine the
+	// * `AUTO:direction` - Specifies to use auto-detection to determine the
 	//   parallel port. Direction can be `BI` to specify bidirectional
 	//   communication or `UNI` to specify unidirectional communication.
 	//
-	// * `NONE` 			- Specifies to not use a parallel port. (default)
+	// * `NONE` - Specifies to not use a parallel port. (default)
 	Parallel string `mapstructure:"parallel" required:"false"`
 }
 
 func (c *HWConfig) Prepare(ctx *interpolate.Context) []error {
 	var errs []error
 
-	if c.CpuCount < 0 {
-		errs = append(errs, fmt.Errorf("invalid number of cpus specified (cpus < 0): %d", c.CpuCount))
+	if (c.Firmware != "") && (!slices.Contains(allowedFirmwareTypes, c.Firmware)) {
+		errs = append(errs, fmt.Errorf("invalid 'firmware' type specified: %s; must be one of %s", c.Firmware, strings.Join(allowedFirmwareTypes, ", ")))
 	}
 
-	if c.MemorySize < 0 {
-		errs = append(errs, fmt.Errorf("invalid amount of memory specified (memory < 0): %d", c.MemorySize))
+	if c.CpuCount < 0 {
+		errs = append(errs, fmt.Errorf("invalid number of cpus specified (cpus < 0): %d", c.CpuCount))
 	}
 
 	if c.CoreCount < 0 {
 		errs = append(errs, fmt.Errorf("invalid number of cpu cores specified (cores < 0): %d", c.CoreCount))
 	}
 
+	if c.MemorySize < 0 {
+		errs = append(errs, fmt.Errorf("invalid amount of memory specified (memory < 0): %d", c.MemorySize))
+	}
+
 	// Peripherals
 	if !c.Sound {
 		c.Sound = false
@@ -147,13 +167,16 @@ type ParallelUnion struct {
 	Device *ParallelPortDevice
 	Auto   *ParallelPortAuto
 }
+
 type ParallelPortFile struct {
 	Filename string
 }
+
 type ParallelPortDevice struct {
 	Bidirectional string
 	Devicename    string
 }
+
 type ParallelPortAuto struct {
 	Bidirectional string
 }