[shimV2] adds the mount controller

Adds the `mount` package to manage the guest-side lifecycle of SCSI
disks and Plan9 shares in Hyper-V utility VMs.

Key features include:
- A `Manager` entry point providing explicit Mount/Unmount APIs.
- Reference-counted mounts to safely allow multiple callers to share
  the same guest path without conflicts.
- An explicit, forward-moving state machine (`Pending` -> `Mounted` ->
  `Unmounted` or `Invalid`) for robust lifecycle tracking.
- Platform-aware delegation supporting SCSI on both LCOW/WCOW, and
  Plan9 on LCOW.

This package is designed to operate downstream of device managers,
handling strictly the guest-side mount while the device manager
maintains host-side lifetime ownership.

Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

Author: rawahars

internal/controller/mount/doc.go

@@ -0,0 +1,87 @@
+//go:build windows
+
+// Package mount manages the lifecycle of guest-level mounts for Hyper-V
+// utility VMs.
+//
+// # Architecture
+//
+// The [Manager] type is the primary entry point.  It exposes a set of APIs
+// that handles guest mounts for both SCSI disks and Plan9 shares,
+// with a dedicated Resolve/Mount/Unmount API for each device type.
+//
+// Internally, Manager tracks guest-level mounts for each device type,
+// each of which has its own explicit state machine.  Mounts are reference-counted
+// so that multiple callers sharing the same guest path do not conflict.
+// Caller should resolve the guest path prior to invoking Mount API.
+//
+// # Device manager integration
+//
+// This package is designed to work downstream of the device managers:
+//
+//   - After [device.scsi.AttachDiskToVM] returns a [VMSlot], pass its
+//     Controller and LUN fields to [Manager.MountSCSI].
+//   - After [device.plan9.AddToVM] returns a shareName, pass it to
+//     [Manager.MountPlan9].
+//
+// The device manager owns the host-side lifetime of the device.  The mount
+// manager owns only the guest-side mount.  Callers must ensure the device
+// is attached before mounting, and must unmount before detaching.
+//
+// # SCSI mounts
+//
+// SCSI mounts are supported on both LCOW and WCOW guests.  The Manager
+// delegates to platform specific guest operator based on the build
+// tag (linux shim vs. windows shim).
+//
+// # Plan9 mounts
+//
+// Plan9 mounts are LCOW-only (Plan9 is a Linux guest protocol).
+// The Manager delegates to Linux guest operator for
+// the actual GCS add/remove-mapped-directory requests.
+//
+// # Reference counting
+//
+// Both SCSI and Plan9 mounts are ref-counted.  When two callers mount the
+// same resource at the same guest path with the same config, they share a
+// single mount entry.  The guest-side unmount only happens when the last
+// reference is released.
+//
+// # State Machine
+//
+// Every mount (SCSI or Plan9) carries a [mountState].  States move forward
+// only.
+//
+// Each mount entry progresses through the states below.
+// The happy path runs down the left column; the error path is on the right.
+//
+//	Mount operation requested
+//	           │
+//	           ▼
+//	┌─────────────────────┐
+//	│    mountPending     │
+//	└──────────┬──────────┘
+//	           │
+//	   ┌───────┴────────────────────────────────┐
+//	   │ mountInGuest succeeds                  │ mountInGuest fails
+//	   ▼                                        ▼
+//	┌─────────────────────┐         ┌──────────────────────┐
+//	│    mountMounted     │         │     mountInvalid     │
+//	└──────────┬──────────┘         └──────────┬───────────┘
+//	           │ unmountFromGuest              │
+//	           │   succeeds                    │
+//	           ▼                               ▼
+//	┌─────────────────────┐          (auto-removed from map)
+//	│   mountUnmounted    │  ← terminal; entry removed from map
+//	└─────────────────────┘
+//
+// State descriptions:
+//
+//   - [mountPending]: entered when a mount operation begins.
+//     The guest mount call has not yet completed.
+//   - [mountMounted]: entered once mountInGuest succeeds; the guest path
+//     is accessible inside the VM.
+//   - [mountUnmounted]: entered once unmountFromGuest succeeds;
+//     the guest path is no longer accessible.  Terminal state.
+//   - [mountInvalid]: entered when mountInGuest fails; concurrent waiters
+//     receive the original error and the entry is removed from the map.
+package mount

internal/controller/mount/mount.go

@@ -0,0 +1,60 @@
+//go:build windows
+
+package mount
+
+import "sync"
+
+// Manager tracks guest-level mounts for SCSI and Plan9 devices, and delegates
+// to the appropriate OS-specific guest manager for the actual GCS calls.
+type Manager struct {
+	// globalMu protects all four mount maps (scsiByPath, scsiByDisk, plan9ByPath,
+	// plan9ByShare) and serializes path allocation across concurrent callers.
+	globalMu sync.Mutex
+
+	// scsiByPath is the global index of SCSI mounts, keyed by guest path.
+	// Two callers mounting the same disk at the same path share one scsiMount
+	// entry and jointly hold its refCount.
+	// Access must be guarded by globalMu.
+	scsiByPath map[string]*scsiMount
+
+	// scsiByDisk maps a SCSI disk (controller + LUN) to its resolved guest path.
+	// Access must be guarded by globalMu.
+	scsiByDisk map[scsiDisk]string
+
+	// plan9ByPath is the global index of Plan9 mounts, keyed by guest path.
+	// Access must be guarded by globalMu.
+	plan9ByPath map[string]*plan9Mount
+
+	// plan9ByShare maps a Plan9 share name to its resolved guest path.
+	// Access must be guarded by globalMu.
+	plan9ByShare map[string]string
+
+	// nextSCSIMountIdx generates stable unique guest paths for SCSI auto-paths.
+	nextSCSIMountIdx int
+
+	// nextPlan9MountIdx generates stable unique guest paths for Plan9 auto-paths.
+	nextPlan9MountIdx int
+
+	// Interfaces used for performing guest actions.
+	linuxGuestSCSI   linuxGuestSCSI
+	windowsGuestSCSI windowsGuestSCSI
+	linuxGuestPlan9  linuxGuestPlan9
+}
+
+// New creates a new instance of mount.Manager which can be used
+// for perform SCSI and Plan9 mount operations.
+func New(
+	linuxGuestSCSI linuxGuestSCSI,
+	windowsGuestSCSI windowsGuestSCSI,
+	linuxGuestPlan9 linuxGuestPlan9,
+) *Manager {
+	return &Manager{
+		scsiByPath:       make(map[string]*scsiMount),
+		scsiByDisk:       make(map[scsiDisk]string),
+		plan9ByPath:      make(map[string]*plan9Mount),
+		plan9ByShare:     make(map[string]string),
+		linuxGuestSCSI:   linuxGuestSCSI,
+		windowsGuestSCSI: windowsGuestSCSI,
+		linuxGuestPlan9:  linuxGuestPlan9,
+	}
+}

internal/controller/mount/mount_types.go

@@ -0,0 +1,130 @@
+//go:build windows
+
+package mount
+
+import (
+	"context"
+	"sync"
+
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+)
+
+// ==============================================================================
+// Exported data structures
+// ==============================================================================
+
+// SCSIMountConfig describes how a SCSI disk should be mounted inside the guest.
+type SCSIMountConfig struct {
+	// GuestPath is the path inside the guest where the disk will be mounted.
+	// Must be non-empty.
+	GuestPath string
+	// Partition is the target partition index (1-based) on a partitioned device.
+	// Only supported for LCOW.
+	Partition uint64
+	// ReadOnly mounts the disk read-only.
+	ReadOnly bool
+	// Encrypted encrypts the device with dm-crypt.
+	// Only supported for LCOW.
+	Encrypted bool
+	// Options are mount flags or data passed to the guest mount call.
+	// Only supported for LCOW.
+	Options []string
+	// EnsureFilesystem formats the mount as Filesystem if not already formatted.
+	// Only supported for LCOW.
+	EnsureFilesystem bool
+	// Filesystem is the target filesystem type.
+	// Only supported for LCOW.
+	Filesystem string
+	// BlockDev mounts the device as a block device.
+	// Only supported for LCOW.
+	BlockDev bool
+	// FormatWithRefs formats the disk using refs.
+	// Only supported for WCOW scratch disks.
+	FormatWithRefs bool
+}
+
+// Plan9MountConfig describes how a Plan9 share should be mounted inside the guest.
+type Plan9MountConfig struct {
+	// GuestPath is the path inside the guest where the share will be mounted.
+	// Must be non-empty.
+	GuestPath string
+	// ReadOnly mounts the share read-only.
+	ReadOnly bool
+}
+
+// ==============================================================================
+// Interfaces used by Manager to perform guest actions.
+// ==============================================================================
+
+// linuxGuestSCSI performs LCOW SCSI guest mount/unmount operations.
+type linuxGuestSCSI interface {
+	AddLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error
+	RemoveLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error
+}
+
+// windowsGuestSCSI performs WCOW SCSI guest mount/unmount operations.
+type windowsGuestSCSI interface {
+	AddWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
+	AddWCOWMappedVirtualDiskForContainerScratch(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
+	RemoveWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
+}
+
+// linuxGuestPlan9 performs Plan9 guest mount/unmount operations in an LCOW guest.
+type linuxGuestPlan9 interface {
+	AddLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
+	RemoveLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
+}
+
+// ==============================================================================
+// Internal data structures
+// ==============================================================================
+
+// refTracker holds the per-mount concurrency and lifecycle fields shared by
+// both scsiMount (SCSI) and plan9Mount (Plan9).
+type refTracker struct {
+	// mu serializes state transitions and broadcasts completion to concurrent
+	// waiters: a goroutine that finds a Pending entry simply locks mu and waits
+	// for the owner to move the state to Mounted or Invalid.
+	mu sync.Mutex
+
+	// state is the forward-only lifecycle position of this mount.
+	// Access must be guarded by mu.
+	state mountState
+
+	// stateErr records the error that caused a transition to mountInvalid.
+	// Waiters that find the mount in the invalid state return this error so
+	// every caller sees the original failure reason.
+	stateErr error
+
+	// refCount is the number of active callers sharing this mount.
+	// Access must be guarded by mu.
+	refCount uint
+}
+
+// scsiDisk is the composite map key for indexing a SCSI mount by controller and LUN.
+type scsiDisk struct {
+	controller uint
+	lun        uint
+}
+
+// scsiMount tracks one SCSI disk mounted in the guest.
+type scsiMount struct {
+	refTracker
+
+	guestPath  string
+	controller uint
+	lun        uint
+	config     *SCSIMountConfig
+}
+
+// plan9Mount tracks one Plan9 share mounted in the guest.
+type plan9Mount struct {
+	refTracker
+
+	// guestPath is the path inside the guest where the share is mounted.
+	guestPath string
+	// shareName is the Plan9 share name returned by [plan9.AddToVM].
+	shareName string
+	// config holds the mount options used when this share was first mounted.
+	config *Plan9MountConfig
+}