RASCSI/cpp/piscsi_interface.proto
Uwe Seimet b7cb23e391
Add statistics and make scsictl accept generic key/value parameters (#1237/#1238) (#1262)
* Add statistics and make scsictl accept generic key/value parameters
2023-10-30 13:32:45 +01:00

479 lines
17 KiB
Protocol Buffer

//---------------------------------------------------------------------------
//
// SCSI Target Emulator PiSCSI
// for Raspberry Pi
//
// Copyright (C) 2021-2023 Uwe Seimet
//
//---------------------------------------------------------------------------
//
// Each piscsi message sent to the piscsi server is preceded by the magic string "RASCSI".
// A message starts with a little endian 32 bit header which contains the protobuf message size.
// Unless explicitly specified the order of repeated data returned is undefined.
// All operations accept an optional access token, specified by the "token" parameter.
// All operations also accept an optional locale, specified with the "locale" parameter. If there is
// a localized error message piscsi returns it, with English being the fallback language.
//
syntax = "proto3";
package piscsi_interface;
// The available device types
enum PbDeviceType {
UNDEFINED = 0;
// Non-removable SASI drive, not supported anymore but must not be removed because of backwards compatibility
SAHD = 1 [deprecated = true];
// Non-removable SCSI drive
SCHD = 2;
// Removable SCSI drive
SCRM = 3;
// Magnoto-Optical drive
SCMO = 4;
// CD-ROM drive
SCCD = 5;
// Network bridge
SCBR = 6;
// DaynaPort network adapter
SCDP = 7;
// Host services device
SCHS = 8;
// Printer device
SCLP = 9;
}
// piscsi remote operations, returning PbResult
enum PbOperation {
NO_OPERATION = 0;
// Attach devices and return the new device list (PbDevicesInfo)
// Parameters (depending on the device type):
// "file": The filename relative to the default image folder
// "interface": A prioritized comma-separated list of interfaces to create a network bridge for
// "inet": The IP address and netmask for the network bridge
// "cmd": The command to be used for printing, with "%f" as file placeholder
ATTACH = 1;
// Detach a device and return the new device list (PbDevicesInfo)
// Detaches all LUNs of that device which are equal to or higher than the LUN specified.
DETACH = 2;
// Detach all devices, does not require a device list
DETACH_ALL = 3;
// Start device
START = 4;
// Stop device, e.g. park drive
STOP = 5;
// Insert medium
// Parameters:
// "file": The filename, relative to the default image folder
INSERT = 6;
// Eject medium
EJECT = 7;
// Write-protect medium (not possible for read-only media)
PROTECT = 8;
// Make medium writable (not possible for read-only media)
UNPROTECT = 9;
// Gets the server information (PbServerInfo). Calling this operation without a list of operations should
// be avoided because this may return a lot of data. More specific other operations should be used instead.
// Parameters:
// "operations": Optional case insensitive comma-separated list of operation names to return data for,
// e.g. "version_info,log_level_info". Unknown operation names are ignored. If this parameter is missing
// the full set of data supported by PbServerInfo is returned.
// "folder_pattern": Optional filter, only folder names containing the case-insensitive pattern are returned
// "file_pattern": Optional filter, only filenames containing the case-insensitive pattern are returned
SERVER_INFO = 10;
// Get piscsi server version (PbVersionInfo)
VERSION_INFO = 11;
// Get information on attached devices (PbDevicesInfo)
// Returns data for all attached devices if the device list is empty.
DEVICES_INFO = 12;
// Get device properties by device type (PbDeviceTypesInfo)
DEVICE_TYPES_INFO = 13;
// Get information on available image files in the default image folder (PbImageFilesInfo)
// Parameters:
// "folder_pattern": Optional filter, only folder names containing the case-insensitive pattern are returned
// "file_pattern": Optional filter, only filenames containing the case-insensitive pattern are returned
DEFAULT_IMAGE_FILES_INFO = 14;
// Get information on an image file (not necessarily in the default image folder).
// Parameters:
// "file": The filename. Either an absolute path or a path relative to the default image folder.
IMAGE_FILE_INFO = 15;
// Get information on the available log levels and the current log level (PbLogLevelInfo)
LOG_LEVEL_INFO = 16;
// Get the names of the available network interfaces (PbNetworkInterfacesInfo)
// Only lists interfaces that are up.
NETWORK_INTERFACES_INFO = 17;
// Get the mapping of extensions to device types (PbMappingInfo)
MAPPING_INFO = 18;
// Get the list of reserved device IDs (PbReservedIdsInfo)
RESERVED_IDS_INFO = 19;
// Set the default folder for image files. This folder must be located in /home.
// Parameters:
// "folder": The path of the default folder, relative to the user's home folder if relative.
DEFAULT_FOLDER = 20;
// Set the log level.
// Parameters:
// "level": The new log level
LOG_LEVEL = 21;
// Block IDs from being used, usually the IDs of the initiators (computers) in the SCSI chain.
// Parameters:
// "ids": A comma-separated list of IDs to reserve, or an empty string in order not to reserve any ID.
RESERVE_IDS = 22;
// Shut down the piscsi process or shut down/reboot the Pi
// Parameters:
// "mode": The shutdown mode, one of
// "rascsi": Shuts down the piscsi process ("rascsi" instead of "piscsi" for backwards compatibility)
// "system": Shuts down the Pi
// "reboot": Reboots the Pi
SHUT_DOWN = 23;
// Create an image file. The image file must not yet exist.
// Parameters:
// "file": The filename, relative to the default image folder
// "size": The file size in bytes, must be a multiple of 512
// "read_only": Optional, "true" (case-insensitive) in order to create a read-only file
CREATE_IMAGE = 24;
// Delete an image file.
// Parameters:
// "file": The filename, relative to the default image folder.
DELETE_IMAGE = 25;
// Rename/Move an image file.
// Parameters:
// "from": The old filename, relative to the default image folder
// "to": The new filename, relative to the default image folder
// The new filename must not yet exist.
RENAME_IMAGE = 26;
// Copy an image file.
// Parameters:
// "from": The source filename, relative to the default image folder
// "to": The destination filename, relative to the default image folder
// "read_only": Optional, "true" (case-insensitive) in order to create a read-only file
// The destination filename must not yet exist.
COPY_IMAGE = 27;
// Write-protect an image file.
// Parameters:
// "file": The filename, relative to the default image folder
PROTECT_IMAGE = 28;
// Make an image file writable.
// Parameters:
// "file": The filename, relative to the default image folder
UNPROTECT_IMAGE = 29;
// Check whether an authentication token is valid. A client can use this operation in order to
// find out whether piscsi authentication is enable or to use piscsi authentication for securing
// client-internal operations.
CHECK_AUTHENTICATION = 30;
// Get operation meta data (PbOperationInfo)
OPERATION_INFO = 31;
// Get statistics (PbStatisticsInfo)
STATISTICS_INFO = 32;
}
// The operation parameter meta data. The parameter data type is provided by the protobuf API.
message PbOperationParameter {
string name = 1;
// Optional short description
string description = 2;
// There is no specific set of permitted values if empty
repeated string permitted_values = 3;
// Optional default value
string default_value = 4;
// True if this parameter is mandatory
bool is_mandatory = 5;
}
// The list of parameters supported by an operation
message PbOperationMetaData {
// The operation name at the time the server-side protobuf code was generated.
string server_side_name = 1;
// Optional short description
string description = 2;
repeated PbOperationParameter parameters = 3;
}
// Mapping of operations to their ordinals
message PbOperationInfo {
map<int32, PbOperationMetaData> operations = 1;
}
// piscsi special purpose error codes for cases where a textual error message may not be not sufficient.
// The client may react on this code, e.g. by prompting the user for an authentication token.
enum PbErrorCode {
// No error code available
NO_ERROR_CODE = 0;
// The client sent an operation code not supported by this server
UNKNOWN_OPERATION = 1;
// Authentication/Authorization error
UNAUTHORIZED = 2;
}
// The supported file extensions mapped to their respective device types
message PbMappingInfo {
map<string, PbDeviceType> mapping = 1;
}
// The properties supported by a device
message PbDeviceProperties {
// Read-only media (e.g. CD-ROMs) are not protectable but permanently read-only
bool read_only = 1;
// Medium can be write-protected
bool protectable = 2;
// Device can be stopped, e.g. parked
bool stoppable = 3;
// Medium can be removed
bool removable = 4;
// Medium can be locked
bool lockable = 5;
// Device supports image file as a parameter
bool supports_file = 6;
// Device supports parameters other than a filename
bool supports_params = 7;
// List of default parameters, if any (requires supports_params to be true)
map<string, string> default_params = 8;
// LUN numbers this device can have, usually 32
int32 luns = 9;
// Unordered list of permitted block sizes in bytes, empty if the block size is not configurable
repeated uint32 block_sizes = 10;
}
// The status of a device, only meaningful if the respective feature is supported
message PbDeviceStatus {
// Medium is write-protected
bool protected = 1;
// Device is stopped, e.g. parked
bool stopped = 2;
// Medium is removed
bool removed = 3;
// Medium is locked
bool locked = 4;
}
// Device properties by device type. (Note that a protobuf map cannot be used because enums cannot be map keys.)
message PbDeviceTypeProperties {
PbDeviceType type = 1;
PbDeviceProperties properties = 2;
}
message PbDeviceTypesInfo {
repeated PbDeviceTypeProperties properties = 1;
}
// The image file data
message PbImageFile {
string name = 1;
// The assumed device type, based on the filename extension
PbDeviceType type = 2;
// The file size in bytes, 0 for block devices in /dev
uint64 size = 3;
bool read_only = 4;
}
// The default image folder and the image files it contains
message PbImageFilesInfo {
string default_image_folder = 1;
repeated PbImageFile image_files = 2;
// The maximum nesting depth, configured with the -R option
int32 depth = 3;
}
// Log level information
message PbLogLevelInfo {
// List of available log levels, ordered by increasing by severity
repeated string log_levels = 2;
string current_log_level = 3;
}
// The network interfaces information
message PbNetworkInterfacesInfo {
repeated string name = 1;
}
// Statistics categories ordered by increasing severity
enum PbStatisticsCategory {
CATEGORY_NONE = 0;
CATEGORY_INFO = 1;
CATEGORY_WARNING = 2;
CATEGORY_ERROR = 3;
}
message PbStatistics {
PbStatisticsCategory category = 1;
// The device ID and LUN for this statistics item. Both are -1 if the item is not device specific.
int32 id = 2;
int32 unit = 3;
// A symbolic unique item name, may be used for I18N. Supported values and their categories:
// "read_error_count" (ERROR, SCHD/SCRM/SCMO/SCCD)
// "write_error_count" (ERROR, SCHD/SCRM/SCMO)
// "cache_miss_read_count" (INFO, SCHD/SCRM/SCMO/SCCD)
// "cache_miss_write_count" (INFO, SCHD/SCRM/SCMO)
// "sector_read_count" (INFO, SCHD/SCRM/SCMO/SCCD)
// "sector_write_count" (INFO, SCHD/SCRM/SCMO)
// "byte_read_count" (INFO, SCDP)
// "byte_write_count" (INFO, SCDP)
// "print_error_count" (ERROR, SCLP)
// "print_warning_count" (WARNING, SCLP)
// "file_print_count" (INFO, SCLP)
// "byte_receive_count" (INFO, SCLP)
string key = 4;
uint64 value = 5;
}
// The information on collected statistics
message PbStatisticsInfo {
repeated PbStatistics statistics = 1;
}
// The device definition, sent from the client to the server
message PbDeviceDefinition {
int32 id = 1;
int32 unit = 2;
PbDeviceType type = 3;
// Device specific named parameters, e.g. the name of an image file
map<string, string> params = 4;
// The optional block size in bytes per sector, must be one of the supported block sizes
int32 block_size = 5;
// The device name components
string vendor = 6;
string product = 7;
string revision = 8;
// Create a write-protected device
bool protected = 9;
}
// The device data, sent from the server to the client
message PbDevice {
int32 id = 1;
int32 unit = 2;
PbDeviceType type = 3;
PbDeviceProperties properties = 4;
PbDeviceStatus status = 5;
// Image file information, if the device supports image files
PbImageFile file = 6;
// Effective parameters the device was created with
map<string, string> params = 7;
string vendor = 8;
string product = 9;
string revision = 10;
// Block size in bytes
int32 block_size = 11;
// Number of blocks
uint64 block_count = 12;
}
message PbDevicesInfo {
repeated PbDevice devices = 1;
}
// The reserved device IDs
message PbReservedIdsInfo {
repeated int32 ids = 1;
}
// Piscsi server version information
message PbVersionInfo {
// The piscsi version
int32 major_version = 1;
int32 minor_version = 2;
// < 0 for a development version, = 0 if there is no patch yet
int32 patch_version = 3;
}
// Commands piscsi can execute and their parameters
message PbCommand {
PbOperation operation = 1;
// The non-empty list of devices for this command
repeated PbDeviceDefinition devices = 2;
// The named parameters for the operation, e.g. a filename, or a network interface list
map<string, string> params = 3;
}
// The result of a command
message PbResult {
// false means that an error occurred
bool status = 1;
// An optional error or information message, depending on the status. A string without trailing CR/LF.
string msg = 2;
// An optional error code. Only to be used in cases where textual information is not sufficient.
PbErrorCode error_code = 14;
// Optional additional result data
oneof result {
// The result of a SERVER_INFO command
PbServerInfo server_info = 3;
// The result of a VERSION_INFO command
PbVersionInfo version_info = 4;
// The result of a LOG_LEVEL_INFO command
PbLogLevelInfo log_level_info = 5;
// The result of a DEVICES_INFO, ATTACH or DETACH command
PbDevicesInfo devices_info = 6;
// The result of a DEVICE_TYPES_INFO command
PbDeviceTypesInfo device_types_info = 7;
// The result of a DEFAULT_IMAGE_FILES_INFO command
PbImageFilesInfo image_files_info = 8;
// The result of an IMAGE_FILE_INFO command
PbImageFile image_file_info = 9;
// The result of a NETWORK_INTERFACES_INFO command
PbNetworkInterfacesInfo network_interfaces_info = 10;
// The result of an MAPPING_INFO command
PbMappingInfo mapping_info = 11;
// The result of a RESERVED_IDS_INFO command
PbReservedIdsInfo reserved_ids_info = 12;
// The result of an OPERATION_INFO command
PbOperationInfo operation_info = 13;
// The result of a STATISTICS_INFO command
PbStatisticsInfo statistics_info = 15;
}
}
// The piscsi server information. All data can also be requested with individual commands.
message PbServerInfo {
// The piscsi server version data
PbVersionInfo version_info = 1;
// The available log levels and the current log level
PbLogLevelInfo log_level_info = 2;
// Supported device types and their properties
PbDeviceTypesInfo device_types_info = 3;
// The image files in the default folder
PbImageFilesInfo image_files_info = 4;
// The available (up) network interfaces
PbNetworkInterfacesInfo network_interfaces_info = 5;
// The extensions to device types mapping
PbMappingInfo mapping_info = 6;
// The reserved device IDs
PbReservedIdsInfo reserved_ids_info = 7;
// The attached devices
PbDevicesInfo devices_info = 8;
// The operation meta data
PbOperationInfo operation_info = 9;
// The statistics
PbStatisticsInfo statistics_info = 10;
}