wip 2

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

Author: rawahars

internal/controller/mount/doc.go

@@ -0,0 +1,61 @@
+//go:build windows
+
+// Package mount manages the lifecycle of guest-level mounts for Hyper-V
+// utility VMs.
+//
+// The [Manager] type is the primary entry point.  It exposes a unified
+// [Controller] interface that handles guest mounts for both SCSI disks and
+// Plan9 shares, with a dedicated Mount/Unmount API for each device type.
+//
+// # Device controller integration
+//
+// This package is designed to work downstream of the device controllers:
+//
+//   - After [scsi.Controller.AttachDiskToVM] returns a [VMSlot], pass its
+//     Controller and LUN fields to [Controller.MountSCSI].
+//   - After [plan9.Controller.AddToVM] returns a shareName, pass it to
+//     [Controller.MountPlan9].
+//
+// The device controller owns the host-side lifetime of the device.  The mount
+// controller 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 [linuxGuestSCSI] or [windowsGuestSCSI] based on the build
+// tag (linux container vs. windows container).
+//
+// # Plan9 mounts
+//
+// Plan9 mounts are LCOW-only (Plan9 is a Linux guest protocol).  On WCOW
+// builds, [Controller.MountPlan9] and [Controller.UnmountPlan9] return an
+// error immediately.  The Manager delegates to [linuxGuestPlan9] 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; on partial failure the state records the furthest point reached so
+// that a retry never repeats work that already succeeded.
+//
+// Mount lifecycle:
+//
+//	(none) ─ mountInGuest ─────────────► Mounted
+//	Mounted ─ unmountFromGuest ────────► Unmounted
+//
+// # Error handling
+//
+// During the mount phase, if the GCS call fails, the mount is not recorded —
+// control returns to the caller with an error.
+//
+// During unmount, errors do not restore the refCount so that a retry knows
+// whether the unmount was attempted.
+package mount

internal/controller/mount/interface.go

@@ -0,0 +1,135 @@
+//go:build windows
+
+package mount
+
+import (
+	"context"
+	"sync"
+
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+)
+
+// Controller exposes unified guest mount operations for SCSI and Plan9 devices.
+//
+// Each device type has its own dedicated Mount/Unmount API.  Callers use the
+// output of the corresponding device controller's Add call to drive the mount:
+//   - SCSI:  [scsi.Controller.AttachDiskToVM] returns a VMSlot → [Controller.MountSCSI]
+//   - Plan9: [plan9.Controller.AddToVM] returns a shareName → [Controller.MountPlan9]
+type Controller interface {
+	// MountSCSI mounts a SCSI disk (identified by controller + LUN) inside the
+	// guest at the path described by cfg. Returns the resolved guest path.
+	MountSCSI(ctx context.Context, controller, lun uint, cfg SCSIMountConfig) (string, error)
+
+	// UnmountSCSI releases a previously mounted SCSI guest path.
+	UnmountSCSI(ctx context.Context, guestPath string) error
+
+	// MountPlan9 mounts a Plan9 share (identified by shareName returned from the
+	// Plan9 device controller's AddToVM) inside the guest. Returns the resolved
+	// guest path.
+	MountPlan9(ctx context.Context, shareName string, cfg Plan9MountConfig) (string, error)
+
+	// UnmountPlan9 releases a previously mounted Plan9 guest path.
+	UnmountPlan9(ctx context.Context, guestPath string) error
+}
+
+// todo: maybe have a Linux controller vs windows controller
+
+// 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.
+	// If empty, a unique path is generated automatically.
+	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.
+	// If empty, a unique path is generated automatically.
+	GuestPath string
+	// ReadOnly mounts the share read-only.
+	ReadOnly bool
+}
+
+// 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
+}
+
+// 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.Controller.AddToVM].
+	shareName string
+	config    *Plan9MountConfig
+}

internal/controller/mount/mount.go

@@ -0,0 +1,51 @@
+//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 the scsiMounts and plan9Mounts maps and serializes
+	// path allocation across concurrent callers.
+	globalMu sync.Mutex
+
+	// scsiMounts is the global index of SCSI mounts. Key = resolved guestPath.
+	// Two callers mounting the same disk at the same path share one scsiMount
+	// entry and jointly hold its refCount.
+	scsiMounts map[string]*scsiMount
+
+	// plan9Mounts is the global index of Plan9 mounts. Key = resolved guestPath.
+	plan9Mounts map[string]*plan9Mount
+
+	// nextSCSIMountIdx generates stable unique guest paths for SCSI auto-paths.
+	nextSCSIMountIdx int
+
+	// nextPlan9MountIdx generates stable unique guest paths for Plan9 auto-paths.
+	nextPlan9MountIdx int
+
+	linuxGuestSCSI   linuxGuestSCSI
+	windowsGuestSCSI windowsGuestSCSI
+	linuxGuestPlan9  linuxGuestPlan9
+}
+
+var _ Controller = (*Manager)(nil)
+
+// New creates a Manager that delegates mount operations to the given guest
+// managers.  Pass nil for guest types that are not applicable to the VM
+// (e.g. pass nil windowsGuestSCSI and nil linuxGuestPlan9 for an LCOW VM that has no WCOW
+// support and no Plan9 shares respectively).
+func New(
+	linuxGuestSCSI linuxGuestSCSI,
+	windowsGuestSCSI windowsGuestSCSI,
+	linuxGuestPlan9 linuxGuestPlan9,
+) *Manager {
+	return &Manager{
+		scsiMounts:       make(map[string]*scsiMount),
+		plan9Mounts:      make(map[string]*plan9Mount),
+		linuxGuestSCSI:   linuxGuestSCSI,
+		windowsGuestSCSI: windowsGuestSCSI,
+		linuxGuestPlan9:  linuxGuestPlan9,
+	}
+}