Chap_API_Storage.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter: Storage support
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\provisionalChapter{Storage Support Definitions}
\label{chap:api_storage}

Distributed and parallel computing systems are increasingly embracing storage hierarchies to meet the diverse data management needs of applications and other systems software in a cost-effective manner.
These hierarchies provide access to a number of distinct storage layers, with each potentially composed of different storage hardware (e.g., HDD, SSD, tape, PMEM), deployed at different locations (e.g., on-node, on-switch, on-site, WAN), and designed using different storage paradigms (e.g., file-based, object-based).
Each of these systems offers unique performance and usage characteristics that storage system users should carefully consider to ensure the most efficient use of storage resources.

PMIx enables users to better understand storage hierarchies by defining attributes that formalize storage system characteristics, state, and other parameters.
These attributes can be queried by applications, I/O libraries and middleware, and workflow systems to discover available storage resources and to inform on which resources are most suitable for different I/O workload requirements.

%%%%%%%%%%%
\provisionalSection{Storage support constants}
\declarestruct{pmix_storage_medium_t}

The \refstruct{pmix_storage_medium_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different types of storage mediums. These can be bitwise OR'd together to accommodate storage systems that mix storage medium types.

\begin{constantdesc}
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_UNKNOWN}{0x0000000000000001}
The storage medium type is unknown.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_TAPE}{0x0000000000000002}
The storage system uses tape media.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_HDD}{0x0000000000000004}
The storage system uses HDDs with traditional SAS, SATA interfaces.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_SSD}{0x0000000000000008}
The storage system uses SSDs with traditional SAS, SATA interfaces.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_NVME}{0x0000000000000010}
The storage system uses SSDs with NVMe interface.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_PMEM}{0x0000000000000020}
The storage system uses persistent memory.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_MEDIUM_RAM}{0x0000000000000040}
The storage system is volatile (e.g., tmpfs).
%
\end{constantdesc}

\adviceimplstart
PMIx implementations should maintain the same ordering for bit-mask values for \refstruct{pmix_storage_medium_t} struct as provided in this standard, since these constants are ordered to provide semantic information that may be of use to PMIx users. Namely, \refstruct{pmix_storage_medium_t} constants are ordered in terms of increasing medium bandwidth.

It is further recommended that implementations should try to allocate empty bits in the mask so that they can be extended to account for new constant definitions corresponding to new storage mediums.
\adviceimplend

\declarestruct{pmix_storage_accessibility_t}

The \refstruct{pmix_storage_accessibility_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different levels of storage accessibility (i.e,. from where a storage system may be accessed). These can be bitwise OR'd together to accommodate storage systems that are accessibile in multiple ways.

\begin{constantdesc}
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_NODE}{0x0000000000000001}
The storage system resources are accessible within the same node.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_SESSION}{0x0000000000000002}
The storage system resources are accessible within the same session.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_JOB}{0x0000000000000004}
The storage system resources are accessible within the same job.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_RACK}{0x0000000000000008}
The storage system resources are accessible within the same rack.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_CLUSTER}{0x0000000000000010}
The storage system resources are accessible within the same cluster.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESSIBILITY_REMOTE}{0x0000000000000020}
The storage system resources are remote.
%
\end{constantdesc}

\declarestruct{pmix_storage_persistence_t}

The \refstruct{pmix_storage_persistence_t}~\provisionalMarker{} is a \code{uint64_t} type that defines a set of bit-mask flags for specifying different levels of persistence for a particular storage system.

\begin{constantdesc}
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_TEMPORARY}{0x0000000000000001}
Data on the storage system is persisted only temporarily (i.e, it does not survive across sessions or node reboots).
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_NODE}{0x0000000000000002}
Data on the storage system is persisted on the node.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_SESSION}{0x0000000000000004}
Data on the storage system is persisted for the duration of the session.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_JOB}{0x0000000000000008}
Data on the storage system is persisted for the duration of the job.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_SCRATCH}{0x0000000000000010}
Data on the storage system is persisted according to scratch storage policies (short-term storage, typically persisted for days to weeks).
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_PROJECT}{0x0000000000000020}
Data on the storage system is persisted according to project storage policies (long-term storage, typically persisted for the duration of a project).
%
\declareconstitemvalueProvisional{PMIX_STORAGE_PERSISTENCE_ARCHIVE}{0x0000000000000040}
Data on the storage system is persisted according to archive storage policies (long-term storage, typically persisted indefinitely).
%
\end{constantdesc}

\declarestruct{pmix_storage_access_type_t}

The \refstruct{pmix_storage_access_type_t}~\provisionalMarker{} is a \code{uint16_t} type that defines a set of bit-mask flags for specifying different storage system access types.

\begin{constantdesc}
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_RD}{0x0001}
Provide information on storage system read operations.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_WR}{0x0002}
Provide information on storage system write operations.
%
\declareconstitemvalueProvisional{PMIX_STORAGE_ACCESS_RDWR}{0x0003}
Provide information on storage system read and write operations.
%
\end{constantdesc}


%%%%%%%%%%%
\provisionalSection{Storage support attributes}
\label{api:struct:attributes:pstrg}

The following attributes may be returned in response to queries (e.g., \refapi{PMIx_Get} or \refapi{PMIx_Query_info}) made by processes or tools.

%
\declareAttributeProvisional{PMIX_STORAGE_ID}{"pmix.strg.id"}{char*}{
An identifier for the storage system (e.g., lustre-fs1, daos-oss1, home-fs)
}

%
\declareAttributeProvisional{PMIX_STORAGE_PATH}{"pmix.strg.path"}{char*}{
Mount point path for the storage system (valid only for file-based storage systems)
}

%
\declareAttributeProvisional{PMIX_STORAGE_TYPE}{"pmix.strg.type"}{char*}{
Type of storage system (i.e., "lustre", "gpfs", "daos", "ext4")
}

%
\declareAttributeProvisional{PMIX_STORAGE_VERSION}{"pmix.strg.ver"}{char*}{
Version string for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_MEDIUM}{"pmix.strg.medium"}{pmix_storage_medium_t}{
Types of storage mediums utilized by the storage system (e.g., SSDs, HDDs, tape)
}

%
\declareAttributeProvisional{PMIX_STORAGE_ACCESSIBILITY}{"pmix.strg.access"}{pmix_storage_accessibility_t}{
Accessibility level of the storage system (e.g., within same node, within same session)
}

%
\declareAttributeProvisional{PMIX_STORAGE_PERSISTENCE}{"pmix.strg.persist"}{pmix_storage_persistence_t}{
Persistence level of the storage system (e.g., sratch storage or achive storage)
}

%
\declareAttributeProvisional{PMIX_QUERY_STORAGE_LIST}{"pmix.strg.list"}{char*}{
Comma-delimited list of storage identifiers (i.e., \refattr{PMIX_STORAGE_ID} types) for available storage systems
}

%
\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_LIMIT}{"pmix.strg.caplim"}{double}{
Overall limit on capacity (in bytes) for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_CAPACITY_USED}{"pmix.strg.capuse"}{double}{
Overall used capacity (in bytes) for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_OBJECT_LIMIT}{"pmix.strg.objlim"}{uint64_t}{
Overall limit on number of objects (e.g., inodes) for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_OBJECTS_USED}{"pmix.strg.objuse"}{uint64_t}{
Overall used number of objects (e.g., inodes) for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_MINIMAL_XFER_SIZE}{"pmix.strg.minxfer"}{double}{
Minimal transfer size (in bytes) for the storage system - this is the storage system's atomic unit of transfer (e.g., block size)
}

%
\declareAttributeProvisional{PMIX_STORAGE_SUGGESTED_XFER_SIZE}{"pmix.strg.sxfer"}{double}{
Suggested transfer size (in bytes) for the storage system
}

%
\declareAttributeProvisional{PMIX_STORAGE_BW_MAX}{"pmix.strg.bwmax"}{double}{
Maximum bandwidth (in bytes/sec) for storage system - provided as the theoretical maximum or the maximum observed bandwidth value
}

%
\declareAttributeProvisional{PMIX_STORAGE_BW_CUR}{"pmix.strg.bwcur"}{double}{
Observed bandwidth (in bytes/sec) for storage system - provided as a recently observed bandwidth value, with the exact measurement interval depending on the storage system and/or PMIx library implementation
}

%
\declareAttributeProvisional{PMIX_STORAGE_IOPS_MAX}{"pmix.strg.iopsmax"}{double}{
Maximum IOPS (in I/O operations per second) for storage system - provided as the theoretical maximum or the maximum observed IOPS value
}

%
\declareAttributeProvisional{PMIX_STORAGE_IOPS_CUR}{"pmix.strg.iopscur"}{double}{
Observed IOPS (in I/O operations per second) for storage system - provided as a recently observed IOPS value, with the exact measurement interval depending on the storage system and/or PMIx library implementation
}

%
\declareAttributeProvisional{PMIX_STORAGE_ACCESS_TYPE}{"pmix.strg.atype"}{pmix_storage_access_type_t}{
Qualifier describing the type of storage access to return information for (e.g., for qualifying \refattr{PMIX_STORAGE_BW_CUR},  \refattr{PMIX_STORAGE_IOPS_CUR}, or \refattr{PMIX_STORAGE_SUGGESTED_XFER_SIZE} attributes)
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%