feat: add usb 3.0 support

Introduces a `usb3` option for enabling USB 3.0 controllers and enforces validation to prevent simultaneous enabling of USB 2.0 and USB 3.0.

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

Author: tenthirtyam

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

@@ -137,8 +137,14 @@ JSON Example:
 - `usb` (bool) - Enable 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.
+  ~> **Note:** USB 2.0 and USB 3.0 controllers cannot be enabled
+  simultaneously. Use either `usb` or `usb3`, but not both.
+
+- `usb3` (bool) - Enable USB 3.0 controllers for the virtual machine.
+  Defaults to `false`.
+  
+  ~> **Note:** USB 3.0 and USB 2.0 controllers cannot be enabled
+  simultaneously. Use either `usb3` or `usb`, but not both.
 
 - `serial` (string) - Add a serial port to the virtual machine. Use a format of
   `Type:option1,option2,...`. Allowed values for the field `Type` include:

builder/vmware/common/hw_config.go

@@ -48,9 +48,15 @@ type HWConfig struct {
 	// Enable 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.
+	// ~> **Note:** USB 2.0 and USB 3.0 controllers cannot be enabled
+	// simultaneously. Use either `usb` or `usb3`, but not both.
 	USB bool `mapstructure:"usb" required:"false"`
+	// Enable USB 3.0 controllers for the virtual machine.
+	// Defaults to `false`.
+	//
+	// ~> **Note:** USB 3.0 and USB 2.0 controllers cannot be enabled
+	// simultaneously. Use either `usb3` or `usb`, but not both.
+	USB3 bool `mapstructure:"usb3" required:"false"`
 	// 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`.
@@ -147,6 +153,15 @@ func (c *HWConfig) Prepare(ctx *interpolate.Context) []error {
 		c.USB = false
 	}
 
+	if !c.USB3 {
+		c.USB3 = false
+	}
+
+	// Validate USB configuration - prevent simultaneous USB 2.0 and USB 3.0
+	if c.USB && c.USB3 {
+		errs = append(errs, fmt.Errorf("USB 2.0 and USB 3.0 controllers cannot be enabled simultaneously; use either 'usb' or 'usb3', but not both"))
+	}
+
 	if c.Parallel == "" {
 		c.Parallel = "none"
 	}

builder/vmware/common/hw_config_test.go

@@ -39,6 +39,10 @@ func TestHWConfigPrepare(t *testing.T) {
 		t.Errorf("peripheral choice (usb) should be conservative: %t", c.USB)
 	}
 
+	if c.USB3 {
+		t.Errorf("peripheral choice (usb3) should be conservative: %t", c.USB3)
+	}
+
 	if strings.ToUpper(c.Parallel) != "NONE" {
 		t.Errorf("parallel port should not be defined: %s", c.Parallel)
 	}
@@ -327,3 +331,81 @@ func TestHWConfigSerial_None(t *testing.T) {
 		t.Errorf("serial port shouldn't exist")
 	}
 }
+
+func TestHWConfigUSBValidation_USB3Only(t *testing.T) {
+	c := new(HWConfig)
+	c.NetworkAdapterType = "vmxnet3"
+	c.USB3 = true
+
+	if errs := c.Prepare(interpolate.NewContext()); len(errs) > 0 {
+		t.Fatalf("err: %#v", errs)
+	}
+
+	if !c.USB3 {
+		t.Errorf("USB 3.0 should be enabled: %t", c.USB3)
+	}
+
+	if c.USB {
+		t.Errorf("USB 2.0 should remain disabled: %t", c.USB)
+	}
+}
+
+func TestHWConfigUSBValidation_USB2Only(t *testing.T) {
+	c := new(HWConfig)
+	c.NetworkAdapterType = "vmxnet3"
+	c.USB = true
+
+	if errs := c.Prepare(interpolate.NewContext()); len(errs) > 0 {
+		t.Fatalf("err: %#v", errs)
+	}
+
+	if !c.USB {
+		t.Errorf("USB 2.0 should be enabled: %t", c.USB)
+	}
+
+	if c.USB3 {
+		t.Errorf("USB 3.0 should remain disabled: %t", c.USB3)
+	}
+}
+
+func TestHWConfigUSBValidation_BothDisabled(t *testing.T) {
+	c := new(HWConfig)
+	c.NetworkAdapterType = "vmxnet3"
+
+	if errs := c.Prepare(interpolate.NewContext()); len(errs) > 0 {
+		t.Fatalf("err: %#v", errs)
+	}
+
+	if c.USB {
+		t.Errorf("USB 2.0 should be disabled by default: %t", c.USB)
+	}
+
+	if c.USB3 {
+		t.Errorf("USB 3.0 should be disabled by default: %t", c.USB3)
+	}
+}
+
+func TestHWConfigUSBValidation_BothEnabled_ShouldError(t *testing.T) {
+	c := new(HWConfig)
+	c.NetworkAdapterType = "vmxnet3"
+	c.USB = true
+	c.USB3 = true
+
+	errs := c.Prepare(interpolate.NewContext())
+	if len(errs) == 0 {
+		t.Fatal("expected validation error when both USB 2.0 and USB 3.0 are enabled")
+	}
+
+	expectedError := "USB 2.0 and USB 3.0 controllers cannot be enabled simultaneously; use either 'usb' or 'usb3', but not both"
+	found := false
+	for _, err := range errs {
+		if err.Error() == expectedError {
+			found = true
+			break
+		}
+	}
+
+	if !found {
+		t.Errorf("expected error message not found. Got errors: %v", errs)
+	}
+}

builder/vmware/iso/config.hcl2spec.go

@@ -40,6 +40,7 @@ type vmxTemplateData struct {
 
 	SoundPresent string
 	UsbPresent   string
+	Usb3Present  string
 
 	SerialPresent  string
 	SerialType     string
@@ -175,6 +176,7 @@ func (s *stepCreateVMX) Run(ctx context.Context, state multistep.StateBag) multi
 
 		SoundPresent: map[bool]string{true: "TRUE", false: "FALSE"}[config.Sound],
 		UsbPresent:   map[bool]string{true: "TRUE", false: "FALSE"}[config.USB],
+		Usb3Present:  map[bool]string{true: "TRUE", false: "FALSE"}[config.USB3],
 
 		SerialPresent:   "FALSE",
 		ParallelPresent: "FALSE",
@@ -509,6 +511,10 @@ sound.autodetect = "TRUE"
 usb.pciSlotNumber = "32"
 usb.present = "{{ .UsbPresent }}"
 
+// USB 3.0
+usb_xhci.present = "{{ .Usb3Present }}"
+usb_xhci.pciSlotNumber = "-1"
+
 // Serial
 serial0.present = "{{ .SerialPresent }}"
 serial0.startConnected = "{{ .SerialPresent }}"