github.com/kata-containers/runtime@v0.0.0-20210505125100-04f29832a923/virtcontainers/device/api/interface.go (about)

     1  // Copyright (c) 2017-2018 Intel Corporation
     2  // Copyright (c) 2018 Huawei Corporation
     3  //
     4  // SPDX-License-Identifier: Apache-2.0
     5  //
     6  
     7  package api
     8  
     9  import (
    10  	"github.com/kata-containers/runtime/virtcontainers/device/config"
    11  	persistapi "github.com/kata-containers/runtime/virtcontainers/persist/api"
    12  	"github.com/sirupsen/logrus"
    13  )
    14  
    15  var devLogger = logrus.WithField("subsystem", "device")
    16  
    17  // SetLogger sets the logger for device api package.
    18  func SetLogger(logger *logrus.Entry) {
    19  	fields := devLogger.Data
    20  	devLogger = logger.WithFields(fields)
    21  }
    22  
    23  // DeviceLogger returns logger for device management
    24  func DeviceLogger() *logrus.Entry {
    25  	return devLogger
    26  }
    27  
    28  // DeviceReceiver is an interface used for accepting devices
    29  // a device should be attached/added/plugged to a DeviceReceiver
    30  type DeviceReceiver interface {
    31  	// these are for hotplug/hot-unplug devices to/from hypervisor
    32  	HotplugAddDevice(Device, config.DeviceType) error
    33  	HotplugRemoveDevice(Device, config.DeviceType) error
    34  
    35  	// this is only for virtio-blk and virtio-scsi support
    36  	GetAndSetSandboxBlockIndex() (int, error)
    37  
    38  	// Offset w.r.t. the sandbox block index, to be used when determining
    39  	// a virtio-block drive name.
    40  	GetSandboxBlockOffset() int
    41  
    42  	UnsetSandboxBlockIndex(int) error
    43  	GetHypervisorType() string
    44  
    45  	// this is for appending device to hypervisor boot params
    46  	AppendDevice(Device) error
    47  }
    48  
    49  // Device is the virtcontainers device interface.
    50  type Device interface {
    51  	Attach(DeviceReceiver) error
    52  	Detach(DeviceReceiver) error
    53  
    54  	// ID returns device identifier
    55  	DeviceID() string
    56  
    57  	// DeviceType indicates which kind of device it is
    58  	// e.g. block, vfio or vhost user
    59  	DeviceType() config.DeviceType
    60  
    61  	// GetMajorMinor returns major and minor numbers
    62  	GetMajorMinor() (int64, int64)
    63  
    64  	// GetHostPath return the device path in the host
    65  	GetHostPath() string
    66  
    67  	// GetDeviceInfo returns device specific data used for hotplugging by hypervisor
    68  	// Caller could cast the return value to device specific struct
    69  	// e.g. Block device returns *config.BlockDrive,
    70  	// vfio device returns []*config.VFIODev,
    71  	// VhostUser device returns []*config.VhostUserDeviceAttrs
    72  	GetDeviceInfo() interface{}
    73  
    74  	// GetAttachCount returns how many times the device has been attached
    75  	GetAttachCount() uint
    76  
    77  	// Reference adds one reference to device then returns final ref count
    78  	Reference() uint
    79  
    80  	// Dereference removes one reference to device then returns final ref count
    81  	Dereference() uint
    82  
    83  	// Save converts Device to DeviceState
    84  	Save() persistapi.DeviceState
    85  
    86  	// Load loads DeviceState and converts it to specific device
    87  	Load(persistapi.DeviceState)
    88  }
    89  
    90  // DeviceManager can be used to create a new device, this can be used as single
    91  // device management object.
    92  type DeviceManager interface {
    93  	NewDevice(config.DeviceInfo) (Device, error)
    94  	RemoveDevice(string) error
    95  	AttachDevice(string, DeviceReceiver) error
    96  	DetachDevice(string, DeviceReceiver) error
    97  	IsDeviceAttached(string) bool
    98  	GetDeviceByID(string) Device
    99  	GetAllDevices() []Device
   100  	LoadDevices([]persistapi.DeviceState)
   101  }