blob: 908f1e7ae81a68ecd814fc6a70d458cb0e2ac8df [file]
// Copyright 2023 The IREE Authors
//
// Licensed under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#ifndef IREE_IO_FILE_HANDLE_H_
#define IREE_IO_FILE_HANDLE_H_
#include <stdint.h>
#include "iree/base/api.h"
#include "iree/io/stream.h"
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
//===----------------------------------------------------------------------===//
// Types and enums
//===----------------------------------------------------------------------===//
// Bits defining which operations are allowed on a file.
typedef uint32_t iree_io_file_access_t;
enum iree_io_file_access_bits_t {
// Allows operations that read from the file.
IREE_IO_FILE_ACCESS_READ = 1u << 0,
// Allows operations that write to the file.
IREE_IO_FILE_ACCESS_WRITE = 1u << 1,
};
//===----------------------------------------------------------------------===//
// iree_io_file_handle_primitive_t
//===----------------------------------------------------------------------===//
// Defines the type of a platform file handle primitive.
// Each type may only be usable in a subset of implementations and platforms and
// may even vary based on the runtime device properties or file instance.
//
// See the notes on each type for requirements; compatibility often requires
// the handle to check and trying to import/export is the most reliable way to
// check for support.
typedef enum iree_io_file_handle_type_e {
// A fixed-size range of host memory.
// The handle creator is responsible for ensuring the memory remains live for
// as long as the file handle referencing it.
IREE_IO_FILE_HANDLE_TYPE_HOST_ALLOCATION = 0u,
// Platform file descriptor (fd).
IREE_IO_FILE_HANDLE_TYPE_FD,
// TODO(benvanik): FILE*, HANDLE, etc.
} iree_io_file_handle_type_t;
// A platform handle to a file primitive.
// Unowned/unreferenced on its own but may be embedded in instances that manage
// lifetime such as iree_io_file_handle_t.
typedef union iree_io_file_handle_primitive_value_t {
// IREE_IO_FILE_HANDLE_TYPE_HOST_ALLOCATION
iree_byte_span_t host_allocation;
// IREE_IO_FILE_HANDLE_TYPE_FD
int fd;
} iree_io_file_handle_primitive_value_t;
// A (type, value) pair describing a system file primitive handle.
typedef struct iree_io_file_handle_primitive_t {
iree_io_file_handle_type_t type;
iree_io_file_handle_primitive_value_t value;
} iree_io_file_handle_primitive_t;
//===----------------------------------------------------------------------===//
// iree_io_file_handle_t
//===----------------------------------------------------------------------===//
typedef void(IREE_API_PTR* iree_io_file_handle_release_fn_t)(
void* user_data, iree_io_file_handle_primitive_t handle_primitive);
// A callback issued when a file is released.
typedef struct {
// Callback function pointer.
iree_io_file_handle_release_fn_t fn;
// User data passed to the callback function. Unowned.
void* user_data;
} iree_io_file_handle_release_callback_t;
// Returns a no-op file release callback that implies that no cleanup is
// required.
static inline iree_io_file_handle_release_callback_t
iree_io_file_handle_release_callback_null(void) {
iree_io_file_handle_release_callback_t callback = {NULL, NULL};
return callback;
}
// A reference-counted file handle wrapping a platform primitive.
// Handles are stateless (unlike file descriptors) and only used to reference
// files.
typedef struct iree_io_file_handle_t iree_io_file_handle_t;
// Wraps a platform file primitive |handle_primitive| in a reference-counted
// file handle. |allowed_access| declares which operations are allowed on the
// handle and may be more restrictive than the underlying platform primitive.
// The optional provided |release_callback| will be issued when the last
// reference to the handle is released.
IREE_API_EXPORT iree_status_t iree_io_file_handle_wrap(
iree_io_file_access_t allowed_access,
iree_io_file_handle_primitive_t handle_primitive,
iree_io_file_handle_release_callback_t release_callback,
iree_allocator_t host_allocator, iree_io_file_handle_t** out_handle);
// Wraps a |host_allocation| in a reference-counted file handle.
// |allowed_access| declares which operations are allowed on the handle and may
// be more restrictive than the underlying memory protection.
// The optional provided |release_callback| will be issued when the last
// reference to the handle is released.
IREE_API_EXPORT iree_status_t iree_io_file_handle_wrap_host_allocation(
iree_io_file_access_t allowed_access, iree_byte_span_t host_allocation,
iree_io_file_handle_release_callback_t release_callback,
iree_allocator_t host_allocator, iree_io_file_handle_t** out_handle);
// Retains the file |handle| for the caller.
IREE_API_EXPORT void iree_io_file_handle_retain(iree_io_file_handle_t* handle);
// Releases the file |handle| and releases the underlying platform primitive if
// the caller held the last owning reference.
IREE_API_EXPORT void iree_io_file_handle_release(iree_io_file_handle_t* handle);
// Returns the allowed access operations on the file |handle|.
// As handles can specify more restrictive access than the underlying platform
// primitive users of the handles must always verify accesses using this value.
IREE_API_EXPORT iree_io_file_access_t
iree_io_file_handle_access(const iree_io_file_handle_t* handle);
// Returns the underlying platform file |handle| primitive value.
// Only valid for as long as the file handle is retained. Closing or otherwise
// invalidating the platform primitive while the handle still has uses will
// result in undefined behavior.
IREE_API_EXPORT iree_io_file_handle_primitive_t
iree_io_file_handle_primitive(const iree_io_file_handle_t* handle);
// Returns the type of the file |handle|.
static inline iree_io_file_handle_type_t iree_io_file_handle_type(
const iree_io_file_handle_t* handle) {
return iree_io_file_handle_primitive(handle).type;
}
// Returns the underlying platform file |handle| primitive value.
// Only valid for as long as the file handle is retained. Closing or otherwise
// invalidating the platform primitive while the handle still has uses will
// result in undefined behavior.
static inline iree_io_file_handle_primitive_value_t iree_io_file_handle_value(
const iree_io_file_handle_t* handle) {
return iree_io_file_handle_primitive(handle).value;
}
// Flushes pending writes of |handle| to its backing storage.
IREE_API_EXPORT iree_status_t
iree_io_file_handle_flush(iree_io_file_handle_t* handle);
//===----------------------------------------------------------------------===//
// iree_io_file_handle_t platform files
//===----------------------------------------------------------------------===//
// Bits indicating how a file is opened.
typedef uint64_t iree_io_file_mode_t;
enum iree_io_file_mode_bits_t {
// Allow reads of both existing and new content.
IREE_IO_FILE_MODE_READ = 1ull << 0,
// Allow writes.
IREE_IO_FILE_MODE_WRITE = 1ull << 1,
// Hints that the file will be accessed at random (more-so than not).
// Mutually exclusive with IREE_IO_FILE_MODE_SEQUENTIAL_SCAN. If no access
// hint is specified the platform will use its default behavior.
IREE_IO_FILE_MODE_RANDOM_ACCESS = 1ull << 2,
// Hints that the file will be accessed sequentially (contiguous reads/writes
// or small skips forward only).
// Mutually exclusive with IREE_IO_FILE_MODE_RANDOM_ACCESS. If no access
// hint is specified the platform will use its default behavior.
IREE_IO_FILE_MODE_SEQUENTIAL_SCAN = 1ull << 3,
// Hints that the library and system caching are not required. May hurt
// performance more than it helps unless the file is very large and
// exclusively accessed as part of bulk transfer operations that are
// page-aligned.
IREE_IO_FILE_MODE_DIRECT = 1ull << 4,
// Ensures the file is deleted when it is closed. Platforms may use this as a
// hint to avoid writing the file contents when cache is available.
IREE_IO_FILE_MODE_TEMPORARY = 1ull << 5,
// Allows subsequent operations to open the file for read access while the
// file is open by the creator.
IREE_IO_FILE_MODE_SHARE_READ = 1ull << 6,
// Allows subsequent operations to open the file for write access while the
// file is open by the creator.
IREE_IO_FILE_MODE_SHARE_WRITE = 1ull << 7,
};
// Creates a new platform file at |path| for usage as defined by |mode|.
// The file will be extended to |initial_size| upon creation.
// Returns IREE_STATUS_ALREADY_EXISTS if the file already exists.
// Returns IREE_STATUS_PERMISSION_DENIED if the file cannot be created.
IREE_API_EXPORT iree_status_t iree_io_file_handle_create(
iree_io_file_mode_t mode, iree_string_view_t path, uint64_t initial_size,
iree_allocator_t host_allocator, iree_io_file_handle_t** out_handle);
// Opens an existing platform file at |path| for usage as defined by |mode|.
// Returns IREE_STATUS_NOT_FOUND if the file does not exist.
// Returns IREE_STATUS_PERMISSION_DENIED if the specified |mode| is disallowed.
IREE_API_EXPORT iree_status_t iree_io_file_handle_open(
iree_io_file_mode_t mode, iree_string_view_t path,
iree_allocator_t host_allocator, iree_io_file_handle_t** out_handle);
//===----------------------------------------------------------------------===//
// iree_io_file_mapping_t
//===----------------------------------------------------------------------===//
// EXPERIMENTAL: this API may change once proper memory objects and views are
// added to iree/base/. This may just end up as a thin wrapper around that
// lower-level API with more fancy features (address placement, commit/decommit,
// etc) left to the lower-level API. We may add new APIs here for flush/sync
// as required.
// Flags used to control the behavior of mapped file views.
typedef uint64_t iree_io_file_mapping_flags_t;
enum iree_io_file_mapping_flag_bits_t {
IREE_IO_FILE_MAPPING_FLAG_NONE = 0u,
// Indicates that the memory access pattern of the view is mostly sequential.
// Hints to the system that an LRU page cache and sequential prefetching are
// likely to be worth it.
//
// Implemented by MADV_SEQUENTIAL.
IREE_IO_FILE_MAPPING_FLAG_SEQUENTIAL_ACCESS = 1ull << 0,
// Enables large page support for the given view, if available.
// Certain mapping modes such as mapping of existing files or opening
// mappings from another process where the allocation was not made with large
// pages may not support large pages and the flag will be silently ignored.
// In either case the memory view will be padded to the
// iree_memory_info_t::large_page_size regardless of whether the pages are
// actually large to the system.
//
// Use large pages to reduce the overhead involved in accessing
// hot-but-non-localized memory views that may otherwise spend a significant
// amount of time/capacity maintaining the TLB. As the platform and
// machine-dependent large page size is often several orders of magnitude
// larger than the normal page size (MB vs. KB) care should be used to only
// apply this to large allocations.
//
// Implemented by FILE_MAP_LARGE_PAGES/MAP_HUGETLB, where available.
IREE_IO_FILE_MAPPING_FLAG_LARGE_PAGES = 1ull << 1,
// Excludes the view memory from minidumps/coredumps.
// This is a hint that the memory in the ranges are not useful to include in
// dumps, such as large chunks of read-only file data (model weights, images,
// etc).
//
// Implemented by WerRegisterExcludedMemoryBlock/MADV_DONTDUMP, where
// available.
IREE_IO_FILE_MAPPING_FLAG_EXCLUDE_FROM_DUMPS = 1ull << 2,
// Privately map the memory into the calling process.
// Other processes that may hold a reference to the file will not see changes.
// This is not a guarantee but an optimization to possibly avoid non-trivial
// kernel overheads.
//
// Implemented by MAP_PRIVATE, where available.
IREE_IO_FILE_MAPPING_FLAG_PRIVATE = 1ull << 3,
};
// A mapped file view into host memory.
//
// Thread-safe; the mapping is immutable and may be accessed from any thread.
// The **contents** of the mapping in the file should be coherent across threads
// within the same process but may not be across threads in different processes.
typedef struct iree_io_file_mapping_t iree_io_file_mapping_t;
// Maps a view of a file into host-accessible memory.
// The provided file |handle| is retained for the lifetime of the view.
// To map the entire file specify a range of [0, IREE_HOST_SIZE_MAX].
//
// If the provided file |handle| is already available for use as a host pointer
// it is returned directly.
IREE_API_EXPORT iree_status_t iree_io_file_map_view(
iree_io_file_handle_t* handle, iree_io_file_access_t access,
uint64_t offset, iree_host_size_t length,
iree_io_file_mapping_flags_t flags, iree_allocator_t host_allocator,
iree_io_file_mapping_t** out_mapping);
// Retains the file |mapping| for the caller. The backing file handle will be
// retained as well.
IREE_API_EXPORT void iree_io_file_mapping_retain(
iree_io_file_mapping_t* mapping);
// Releases the file |mapping| and its reference to the backing file handle.
// If the mapping was the last remaining retainer of the handle it will be
// closed.
IREE_API_EXPORT void iree_io_file_mapping_release(
iree_io_file_mapping_t* mapping);
// Returns the length of the mapped view in bytes.
IREE_API_EXPORT iree_host_size_t
iree_io_file_mapping_length(const iree_io_file_mapping_t* mapping);
// Returns a host-accessible read-only pointer to the file mapping memory.
// Returns iree_const_byte_span_empty if the mapping is not readable.
IREE_API_EXPORT iree_const_byte_span_t
iree_io_file_mapping_contents_ro(const iree_io_file_mapping_t* mapping);
// Returns a host-accessible read-write pointer to the file mapping memory.
// Returns iree_byte_span_empty if the mapping is not writable.
IREE_API_EXPORT iree_byte_span_t
iree_io_file_mapping_contents_rw(iree_io_file_mapping_t* mapping);
//===----------------------------------------------------------------------===//
// iree_io_stream_t utilities
//===----------------------------------------------------------------------===//
// TODO(benvanik): remove/rework iree_io_stream_open so that it doesn't pull in
// any implementations by putting callbacks on the file handle constructors.
// Opens a stream from the given |file_handle| at the absolute |file_offset|.
// The returned stream will retain the file until it is released.
IREE_API_EXPORT iree_status_t iree_io_stream_open(
iree_io_stream_mode_t mode, iree_io_file_handle_t* file_handle,
uint64_t file_offset, iree_allocator_t host_allocator,
iree_io_stream_t** out_stream);
// Writes up to |length| bytes of |source_file_handle| starting at offset
// |source_file_offset| to the target |stream|. |host_allocator| may be used
// for transient allocations required during file I/O.
IREE_API_EXPORT iree_status_t iree_io_stream_write_file(
iree_io_stream_t* stream, iree_io_file_handle_t* source_file_handle,
uint64_t source_file_offset, iree_io_stream_pos_t length,
iree_allocator_t host_allocator);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // IREE_IO_FILE_HANDLE_H_