path: root/src/H5FDmirror.h

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Purpose: Public, shared definitions for Mirror VFD & remote Writer.
 */

#ifndef H5FDmirror_H
#define H5FDmirror_H

#ifdef H5_HAVE_MIRROR_VFD

#define H5FD_MIRROR (H5FD_mirror_init())

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================================
 * Mirror VFD use and operation.
 * ============================================================================
 */

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_fapl_t
 *
 * Used to pass configuraiton information to the Mirror VFD.
 * Populate components as appropriate and pass structure pointer to
 * `H5Pset_fapl_mirror()`.
 *
 * `magic` (uint32_t)
 *      Semi-unique number to sanity-check pointers to this structure type.
 *      MUST equal H5FD_MIRROR_FAPL_MAGIC to be considered valid.
 *
 * `version` (uint32_t)
 *      Indicates expected components of the structure.
 *
 * `handshake_port (int)
 *      Port number to expect to reach the "Mirror Server" on the remote host.
 *
 * `remote_ip` (char[])
 *      IP address string of "Mirror Server" remote host.
 * ---------------------------------------------------------------------------
 */
#define H5FD_MIRROR_FAPL_MAGIC          0xF8DD514C
#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1
#define H5FD_MIRROR_MAX_IP_LEN          32
typedef struct H5FD_mirror_fapl_t {
    uint32_t magic;
    uint32_t version;
    int      handshake_port;
    char     remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1];
} H5FD_mirror_fapl_t;

H5_DLL hid_t  H5FD_mirror_init(void);
H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out);
H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa);

/* = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 * IPC - Mirror VFD and Remote Worker application.
 * = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 */

/* The maximum allowed size for a receiving buffer when accepting bytes to
 * write. Writes larger than this size are performed by multiple accept-write
 * steps by the Writer. */
#define H5FD_MIRROR_DATA_BUFFER_MAX H5_GB /* 1 Gigabyte */

#define H5FD_MIRROR_XMIT_CURR_VERSION 1
#define H5FD_MIRROR_XMIT_MAGIC        0x87F8005B

#define H5FD_MIRROR_OP_OPEN     1
#define H5FD_MIRROR_OP_CLOSE    2
#define H5FD_MIRROR_OP_WRITE    3
#define H5FD_MIRROR_OP_TRUNCATE 4
#define H5FD_MIRROR_OP_REPLY    5
#define H5FD_MIRROR_OP_SET_EOA  6
#define H5FD_MIRROR_OP_LOCK     7
#define H5FD_MIRROR_OP_UNLOCK   8

#define H5FD_MIRROR_STATUS_OK          0
#define H5FD_MIRROR_STATUS_ERROR       1
#define H5FD_MIRROR_STATUS_MESSAGE_MAX 256 /* Dedicated error message size */

/* Maximum length of a path/filename string, including the NULL-terminator.
 * Must not be smaller than H5FD_SPLITTER_PATH_MAX. */
#define H5FD_MIRROR_XMIT_FILEPATH_MAX 4097

/* Define the exact sizes of the various xmit blobs as sent over the wire.
 * This is used to minimize the number of bytes transmitted as well as to
 * sanity-check received bytes.
 * Any modifications to the xmit structures and/or the encode/decode functions
 * must be reflected here.
 * */
#define H5FD_MIRROR_XMIT_HEADER_SIZE 14
#define H5FD_MIRROR_XMIT_EOA_SIZE    (H5FD_MIRROR_XMIT_HEADER_SIZE + 9)
#define H5FD_MIRROR_XMIT_LOCK_SIZE   (H5FD_MIRROR_XMIT_HEADER_SIZE + 8)
#define H5FD_MIRROR_XMIT_OPEN_SIZE   (H5FD_MIRROR_XMIT_HEADER_SIZE + 20 + H5FD_MIRROR_XMIT_FILEPATH_MAX)
#define H5FD_MIRROR_XMIT_REPLY_SIZE  (H5FD_MIRROR_XMIT_HEADER_SIZE + 4 + H5FD_MIRROR_STATUS_MESSAGE_MAX)
#define H5FD_MIRROR_XMIT_WRITE_SIZE  (H5FD_MIRROR_XMIT_HEADER_SIZE + 17)

/* Maximum length of any xmit. */
#define H5FD_MIRROR_XMIT_BUFFER_MAX                                                                          \
    MAX2(MAX3(H5FD_MIRROR_XMIT_HEADER_SIZE, H5FD_MIRROR_XMIT_EOA_SIZE, H5FD_MIRROR_XMIT_LOCK_SIZE),          \
         MAX3(H5FD_MIRROR_XMIT_OPEN_SIZE, H5FD_MIRROR_XMIT_REPLY_SIZE, H5FD_MIRROR_XMIT_WRITE_SIZE))

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_xmit_t
 *
 * Common structure 'header' for all mirror VFD/worker IPC.
 * Must be the first component of a derived operation xmit structure,
 * such as file-open or write command.
 *
 * `magic` (uint32_t)
 *      A "unique" number identifying the structure and endianness of
 *      transmitting maching.
 *      Must be set to H5FD_MIRROR_XMIT_MAGIC native to the VFD "sender".
 *
 * `version` (uint8_t)
 *      Number used to identify the structure membership.
 *      Allows sane modifications to this structure in the future.
 *      Must be set to H5FD_MIRROR_XMIT_CURR_VERSION.
 *
 * `session_token` (uint32_t)
 *      A "unique" number identifying the session between VFD sender and
 *      remote receiver/worker/writer. Exists to help sanity-check.
 *
 * `xmit_count` (uint32_t)
 *      Which transmission this is since the session began.
 *      Used to sanity-check transmission errors.
 *      First xmit (file-open) must be 0.
 *
 * `op` (uint8_t)
 *      Number identifying which operation to perform.
 *      Corresponds with the extended structure outside of this xmit header.
 *      Possible values are all defined H5FD_MIRROR_OP_* constants.
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_t {
    uint32_t magic;
    uint8_t  version;
    uint32_t session_token;
    uint32_t xmit_count;
    uint8_t  op;
} H5FD_mirror_xmit_t;

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_xmit_eoa_t
 *
 * Structure containing eoa-set information from VFD sender.
 *
 * `pub` (H5FD_mirror_xmit_t)
 *      Common transmission header, containing session information.
 *      Must be first.
 *
 * `type` (uint8_t)
 *      System-independent alias for H5F[D]_mem_t.
 *      Specifies datatype to be written.
 *
 * `eoa_addr` (uint64_t)
 *      New address for eoa.
 *      (Natively 'haddr_t', always a 64-bit field)
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_eoa_t {
    H5FD_mirror_xmit_t pub;
    uint8_t            type;
    uint64_t           eoa_addr;
} H5FD_mirror_xmit_eoa_t;

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_xmit_lock_t
 *
 * Structure containing eoa-set information from VFD sender.
 *
 * `pub` (H5FD_mirror_xmit_t)
 *      Common transmission header, containing session information.
 *      Must be first.
 *
 * `rw` (uint64_t)
 *      The Read/Write mode flag passed into H5FDlock().
 *      (Natively `hbool_t`, an 'int') TODO: native int may be 64-bit?
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_lock_t {
    H5FD_mirror_xmit_t pub;
    uint64_t           rw;
} H5FD_mirror_xmit_lock_t;

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_xmit_open_t
 *
 * Structure containing file-open information from the VFD sender.
 *
 * `pub` (H5FD_mirror_xmit_t)
 *      Common transmission header, containing session information.
 *      Must be first.
 *
 * `flags` (uint32_t)
 *      VFL-layer file-open flags passed directly to H5FDopen().
 *      (Natively 'unsigned [int]') TODO: native int may be 64-bit?
 *
 * `maxaddr` (uint64_t)
 *      VFL-layer maximum allowed address space for the file to open passed
 *      directly to H5FDopen().
 *      (Natively 'haddr_t', always a 64-bit field)
 *
 * `size_t_blob` (uint64_t)
 *      A number indicating how large a size_t is on the sending system.
 *      Must be set to (uint64_t)((size_t)(-1))
 *          (maximum possible value of size_t, cast to uint64_t).
 *      The receiving system inspects this value -- if the local (remote)
 *      size_t is smaller than that of the Sender, issues a warning.
 *      Not an error, as:
 *      1. It is assumed that underlying file systems/drivers have become
 *         smart enough to handle file sizes that otherwise might be
 *         constrained.
 *      2. The Mirror Writer ingests bytes to write multiple 'slices' if the
 *         size is greater than H5FD_MIRROR_DATA_BUFFER_MAX, regardless of
 *         any size_t storage size disparity.
 *
 * `filename` (char[])
 *      String giving the filename and path of file to open.
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_open_t {
    H5FD_mirror_xmit_t pub;
    uint32_t           flags;
    uint64_t           maxaddr;
    uint64_t           size_t_blob;
    char               filename[H5FD_MIRROR_XMIT_FILEPATH_MAX];
} H5FD_mirror_xmit_open_t;

/* ---------------------------------------------------------------------------
 * Structure: H5FD_mirror_xmit_reply_t
 *
 * Structure used by the remote receiver/worker/writer to respond to
 * a command from the VFD sender.
 *
 * `pub` (H5FD_mirror_xmit_t)
 *      Common transmission header, containing session information.
 *      Must be first.
 *
 * `status` (uint32_t)
 *      Number indicating whether the command was successful or if an
 *      occured.
 *      Allowed values are H5FD_MIRROR_STATUS_OK and
 *      H5FD_MIRROR_STATUS_ERROR.
 *
 * `message` (char[])
 *      Error message. Populated if and only if there was a problem.
 *      It is possible that a message may reach the end of the alloted
 *      space without a NULL terminator -- the onus is on the programmer to
 *      handle this situation.
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_reply_t {
    H5FD_mirror_xmit_t pub;
    uint32_t           status;
    char               message[H5FD_MIRROR_STATUS_MESSAGE_MAX];
} H5FD_mirror_xmit_reply_t;

/* ---------------------------------------------------------------------------
 * Structure:   H5FD_mirror_xmit_write_t
 *
 * Structure containing data-write information from VFD sender.
 *
 * The data to be written is transmitted in subsequent, packets
 * and may be broken up into more than one transmission buffer.
 * The VFD sender and remote receiver/worker/writer must coordinate
 * the receipt of data.
 *
 * `pub` (H5FD_mirror_xmit_t)
 *      Common transmission header, containing session information.
 *      Must be first.
 *
 * `type` (uint8_t)
 *      Specifies datatype to be written.
 *      (Natively 'H5FD_mem_t', an enumerated type in H5Fpublic.h)
 *
 * `offset` (uint64_t)
 *      Start location of write in file.
 *      (Natively 'haddr_t', always a 64-bit field)
 *
 * `size` (uint64_t)
 *      Size of the data to be written, in bytes.
 *      (Natively 'size_t', accommodate the largest possible as 64-bits)
 *
 * ---------------------------------------------------------------------------
 */
typedef struct H5FD_mirror_xmit_write_t {
    H5FD_mirror_xmit_t pub;
    uint8_t            type;
    uint64_t           offset;
    uint64_t           size;
} H5FD_mirror_xmit_write_t;

/* Encode/decode routines are required to "pack" the xmit data into a known
 * byte format for transmission over the wire.
 *
 * All component numbers must be stored in "network" word order (Big-Endian).
 *
 * All components must be packed in the order given in the structure definition.
 *
 * All components must be packed with zero padding between.
 */

H5_DLL size_t H5FD__mirror_xmit_decode_uint16(uint16_t *out, const unsigned char *buf);
H5_DLL size_t H5FD__mirror_xmit_decode_uint32(uint32_t *out, const unsigned char *buf);
H5_DLL size_t H5FD__mirror_xmit_decode_uint64(uint64_t *out, const unsigned char *buf);
H5_DLL size_t H5FD__mirror_xmit_decode_uint8(uint8_t *out, const unsigned char *buf);
H5_DLL size_t H5FD__mirror_xmit_encode_uint16(unsigned char *dest, uint16_t v);
H5_DLL size_t H5FD__mirror_xmit_encode_uint32(unsigned char *dest, uint32_t v);
H5_DLL size_t H5FD__mirror_xmit_encode_uint64(unsigned char *dest, uint64_t v);
H5_DLL size_t H5FD__mirror_xmit_encode_uint8(unsigned char *dest, uint8_t v);

H5_DLL size_t H5FD_mirror_xmit_decode_header(H5FD_mirror_xmit_t *out, const unsigned char *buf);
H5_DLL size_t H5FD_mirror_xmit_decode_lock(H5FD_mirror_xmit_lock_t *out, const unsigned char *buf);
H5_DLL size_t H5FD_mirror_xmit_decode_open(H5FD_mirror_xmit_open_t *out, const unsigned char *buf);
H5_DLL size_t H5FD_mirror_xmit_decode_reply(H5FD_mirror_xmit_reply_t *out, const unsigned char *buf);
H5_DLL size_t H5FD_mirror_xmit_decode_set_eoa(H5FD_mirror_xmit_eoa_t *out, const unsigned char *buf);
H5_DLL size_t H5FD_mirror_xmit_decode_write(H5FD_mirror_xmit_write_t *out, const unsigned char *buf);

H5_DLL size_t H5FD_mirror_xmit_encode_header(unsigned char *dest, const H5FD_mirror_xmit_t *x);
H5_DLL size_t H5FD_mirror_xmit_encode_lock(unsigned char *dest, const H5FD_mirror_xmit_lock_t *x);
H5_DLL size_t H5FD_mirror_xmit_encode_open(unsigned char *dest, const H5FD_mirror_xmit_open_t *x);
H5_DLL size_t H5FD_mirror_xmit_encode_reply(unsigned char *dest, const H5FD_mirror_xmit_reply_t *x);
H5_DLL size_t H5FD_mirror_xmit_encode_set_eoa(unsigned char *dest, const H5FD_mirror_xmit_eoa_t *x);
H5_DLL size_t H5FD_mirror_xmit_encode_write(unsigned char *dest, const H5FD_mirror_xmit_write_t *x);

H5_DLL hbool_t H5FD_mirror_xmit_is_close(const H5FD_mirror_xmit_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_lock(const H5FD_mirror_xmit_lock_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_open(const H5FD_mirror_xmit_open_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_reply(const H5FD_mirror_xmit_reply_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_set_eoa(const H5FD_mirror_xmit_eoa_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_write(const H5FD_mirror_xmit_write_t *xmit);
H5_DLL hbool_t H5FD_mirror_xmit_is_xmit(const H5FD_mirror_xmit_t *xmit);

#ifdef __cplusplus
}
#endif

#else /* H5_HAVE_MIRROR_VFD */

#define H5FD_MIRROR (H5I_INAVLID_HID)

#endif /* H5_HAVE_MIRROR_VFD */

#endif /* H5FDmirror_H */