syntax = "proto3";

import "nvme.proto";
import "virtio_blk.proto";
import "nvmf_tcp.proto";
import "nvmf.proto";

// This file provides the generic definitions for the Storage Management Agent
// gRPC calls.  All of the methods are supposed to be idempotent.  Errors are
// reported as standard gRPC status codes.

package sma;

option go_package = "spdk.io/sma";

// Parameters describing a volume
message VolumeParameters {
  // Volume GUID/UUID
  bytes volume_id = 1;
  oneof connection_params {
    // NVMeoF volume
    nvmf.VolumeConnectionParameters nvmf = 2;
  }
}

// Create device request
message CreateDeviceRequest {
  // Volume to immediately attach to the created device.  This field may be
  // optional for some device types (e.g. NVMe), while it may be required for
  // others (e.g. virtio-blk).
  VolumeParameters volume = 1;
  // Device-specific parameters
  oneof params {
    // NVMe parameters
    nvme.DeviceParameters nvme = 2;
    // Virtio-blk parameters
    virtio_blk.DeviceParameters virtio_blk = 3;
    // NVMe/TCP parameters
    nvmf_tcp.DeviceParameters nvmf_tcp = 4;
  }
}

// Create device response
message CreateDeviceResponse {
  // Device handle that can uniquely identify a device within an instance of
  // Storage Management Agent
  string handle = 1;
}

// Delete device request
message DeleteDeviceRequest {
  // Device handle
  string handle = 1;
}

// Delete device response
message DeleteDeviceResponse {}

// Attach volume request
message AttachVolumeRequest {
  // Volume parameters
  VolumeParameters volume = 1;
  // Device handle
  string device_handle = 2;
}

// Attach volume response
message AttachVolumeResponse {}

// Detach volume request
message DetachVolumeRequest {
  // Volume GUID/UUID
  bytes volume_id = 1;
  // Device handle
  string device_handle = 2;
}

// Detach volume response
message DetachVolumeResponse {}

// Storage Management Agent gRPC service definition
service StorageManagementAgent {
  // Creates a new device.  A device is an entity that can be used to expose
  // volumes (e.g. an NVMeoF subsystem).
  rpc CreateDevice (CreateDeviceRequest)
    returns (CreateDeviceResponse) {}
  // Deletes a device
  rpc DeleteDevice (DeleteDeviceRequest)
    returns (DeleteDeviceResponse) {}
  // Attaches a volume to a specified device making it available through that
  // device (e.g. for NVMeoF this results in adding a namespace to an NVMeoF
  // subsystem).  The type of volume doesn't need to match the type of device
  // (e.g. it's perfectly fine to attach an NVMe/TCP volume to a virtio-blk
  // device).
  rpc AttachVolume (AttachVolumeRequest)
    returns (AttachVolumeResponse) {}
  // Detaches a volume from a device
  rpc DetachVolume (DetachVolumeRequest)
    returns (DetachVolumeRequest) {}
}