firmware

type FirmwareManager interface {
	// ValidateRequestedFirmwareSource will validate the NicFirmwareSource object, requested for NicDevice
	// returns string - requested firmware version
	// returns error - firmware source is not ready or there are errors
	// Possible errors:
	// Referenced NicFirmwareSource obj doesn't exist
	// Source exists but not ready / failed
	// Source exists and ready but doesn't contain an image for this device's PSID
	ValidateRequestedFirmwareSource(ctx context.Context, device *v1alpha1.NicDevice) (string, error)

	// BurnNicFirmware will update the device's FW to the requested version
	// returns error - there were errors while updating firmware
	BurnNicFirmware(ctx context.Context, device *v1alpha1.NicDevice, version string) error

	// InstallDocaSpcXCC will validate and install the DOCA SPC-X CC package if provided in the FirmwareSource
	// If already installed, results in no-op. If package version doesn't match targetVersion, returns an error.
	// returns error - DOCA SPC-X PCC .deb package is not ready or there are errors
	InstallDocaSpcXCC(ctx context.Context, device *v1alpha1.NicDevice, targetVersion string) error

	// GetFirmwareVersionsFromDevice retrieves the burned and running FW versions from the device
	// returns string - burned FW version
	// returns string - running FW version
	// returns error - there were errors while retrieving the firmware versions
	GetFirmwareVersionsFromDevice(device *v1alpha1.NicDevice) (string, string, error)
}

type FirmwareProvisioner interface {
	// IsFWStorageAvailable checks if the cache storage exists in the pod.
	IsFWStorageAvailable() error
	// VerifyCachedBinaries checks against the metadata.json for which urls have corresponding cached fw binary files
	// Returns a list of urls that need to be processed again
	VerifyCachedBinaries(cacheName string, urls []string) ([]string, error)
	// DownloadAndUnzipFirmwareArchives downloads and unzips fw archives from a list of urls
	// Stores a metadata file, mapping download url to file names
	// Returns error if occurred
	DownloadAndUnzipFirmwareArchives(cacheName string, urls []string, cleanupArchives bool) error
	// AddFirmwareBinariesToCacheByMetadata finds the newly downloaded firmware binary files and organizes them in the cache according to their metadata
	AddFirmwareBinariesToCacheByMetadata(cacheName string) error
	// ValidateFirmwareBinariesCache traverses the cache directory and validates that
	// 1. There are no empty directories in the cache
	// 2. Each PSID has only one matching firmware binary in the cache
	// 3. Each non-empty PSID directory contains a firmware binary file (.bin)
	// Returns mapping between firmware version to PSIDs available in the cache, error if validation failed
	ValidateFirmwareBinariesCache(cacheName string) (map[string][]string, error)
	// DeleteCache deletes the cache directory with the given name
	DeleteCache(cacheName string) error
	// VerifyCachedBFB checks if BFB file exists and matches URL in metadata
	// Returns whether re-download is needed, error if occurred
	VerifyCachedBFB(cacheName string, url string) (bool, error)
	// DownloadBFB downloads BFB file, validates it, updates metadata, and returns filename
	// Returns filename on disk, error if occurred
	DownloadBFB(cacheName string, url string) (string, error)
	// ValidateBFB checks if the BFB file exists and is valid
	// Returns BF FW versions available in the BFB
	ValidateBFB(cacheName string) (map[string]string, error)
	// VerifyCachedDocaSpcXCC checks if DOCA SPC-X CC package file exists and matches URL in metadata
	// Returns whether re-download is needed, error if occurred
	VerifyCachedDocaSpcXCC(cacheName string, url string) (bool, error)
	// DownloadDocaSpcXCC downloads DOCA SPC-X CC package file, validates it, updates metadata, and returns filename
	// Returns filename on disk, error if occurred
	DownloadDocaSpcXCC(cacheName string, url string) (string, error)
	// ValidateDocaSpcXCC checks if the DOCA SPC-X CC package file exists and is valid
	// Returns DOCA SPC-X PCC FW version
	ValidateDocaSpcXCC(cacheName string) (string, error)
}

type FirmwareUtils interface {
	// DownloadFile downloads the file under url and places it locally under destPath
	DownloadFile(url, destPath string) error
	// UnzipFiles extract files from the zip archive to destDir
	// Returns a list of extracted files, error if occurred
	UnzipFiles(zipPath, destDir string) ([]string, error)
	// GetFirmwareVersionsFromDevice retrieves the burned and running FW versions from the device
	// returns string - burned FW version
	// returns string - running FW version
	// returns error - there were errors while retrieving the firmware versions
	GetFirmwareVersionsFromDevice(pciAddress string) (string, string, error)
	// GetFirmwareVersionAndPSIDFromFWBinary retrieves the version and PSID from the firmware binary
	GetFirmwareVersionAndPSIDFromFWBinary(firmwareBinaryPath string) (string, string, error)
	// GetFWVersionsFromBFB retrieves the FW versions from the BFB file
	GetFWVersionsFromBFB(bfbPath string) (map[string]string, error)
	// GetDocaSpcXCCVersion retrieves the version from the DOCA SPC-X PCC file
	GetDocaSpcXCCVersion(docaSpcXCCPath string) (string, error)
	// VerifyImageBootable verifies if the image file is valid and bootable
	VerifyImageBootable(firmwareBinaryPath string) error
	// CleanupDirectory deletes any file inside a root directory except for allowedSet. Empty directories are cleaned up as well at the end
	CleanupDirectory(root string, allowedSet map[string]struct{}) error
	// BurnNicFirmware burns the requested firmware on the requested device
	// Operation can be long, require context to be able to terminate by timeout
	BurnNicFirmware(ctx context.Context, pciAddress, fwPath string) error
	// InstallDebPackage installs the .deb package
	InstallDebPackage(debPath string) error
	// GetInstalledDebPackageVersion retrieves the version from the installed .deb package
	// Return empty string if the package is not installed
	GetInstalledDebPackageVersion(packageName string) string
}