diff options
Diffstat (limited to 'src/osd/osdcore.h')
-rw-r--r-- | src/osd/osdcore.h | 676 |
1 files changed, 139 insertions, 537 deletions
diff --git a/src/osd/osdcore.h b/src/osd/osdcore.h index 22179f9da45..b3dc2099913 100644 --- a/src/osd/osdcore.h +++ b/src/osd/osdcore.h @@ -1,284 +1,42 @@ // license:BSD-3-Clause // copyright-holders:Aaron Giles -/*************************************************************************** - - osdcore.h - - Core OS-dependent code interface. - -**************************************************************************** - - The prototypes in this file describe the interfaces that the MAME core - and various tools rely upon to interact with the outside world. They are - broken out into several categories. - -***************************************************************************/ - -#pragma once - +/// \file +/// \brief Core OS-dependent code interface +/// +/// The prototypes in this file describe the interfaces that the MAME +/// core and various tools rely on to interact with the outside world. +/// They are broken out into several categories. #ifndef MAME_OSD_OSDCORE_H #define MAME_OSD_OSDCORE_H +#pragma once + #include "osdcomm.h" -#include <chrono> -#include <cstdarg> +#include "strformat.h" + #include <cstdint> -#include <memory> +#include <iosfwd> #include <string> +#include <string_view> +#include <system_error> +#include <utility> #include <vector> -/*************************************************************************** - FILE I/O INTERFACES -***************************************************************************/ - -/* Make sure we have a path separator (default to /) */ -#ifndef PATH_SEPARATOR -#if defined(_WIN32) -#define PATH_SEPARATOR "\\" -#else -#define PATH_SEPARATOR "/" -#endif -#endif - -/* flags controlling file access */ -#define OPEN_FLAG_READ 0x0001 /* open for read */ -#define OPEN_FLAG_WRITE 0x0002 /* open for write */ -#define OPEN_FLAG_CREATE 0x0004 /* create & truncate file */ -#define OPEN_FLAG_CREATE_PATHS 0x0008 /* create paths as necessary */ -#define OPEN_FLAG_NO_PRELOAD 0x0010 /* do not decompress on open */ - -// osd_file is an interface which represents an open file/PTY/socket -class osd_file -{ -public: - // error codes returned by routines below - enum class error - { - NONE, - FAILURE, - OUT_OF_MEMORY, - NOT_FOUND, - ACCESS_DENIED, - ALREADY_OPEN, - TOO_MANY_FILES, - INVALID_DATA, - INVALID_ACCESS - }; - - typedef std::unique_ptr<osd_file> ptr; - - - /*----------------------------------------------------------------------------- - osd_file::open: open a new file. - - Parameters: - - path - path to the file to open - - openflags - some combination of: - - OPEN_FLAG_READ - open the file for read access - OPEN_FLAG_WRITE - open the file for write access - OPEN_FLAG_CREATE - create/truncate the file when opening - OPEN_FLAG_CREATE_PATHS - specifies that non-existant paths - should be created if necessary - - file - reference to an osd_file::ptr to receive the newly-opened file - handle; this is only valid if the function returns FILERR_NONE - - filesize - reference to a uint64_t to receive the size of the opened - file; this is only valid if the function returns FILERR_NONE - - Return value: - - a file_error describing any error that occurred while opening - the file, or FILERR_NONE if no error occurred - - Notes: - - This function is called by core_fopen and several other places in - the core to access files. These functions will construct paths by - concatenating various search paths held in the options.c options - database with partial paths specified by the core. The core assumes - that the path separator is the first character of the string - PATH_SEPARATOR, but does not interpret any path separators in the - search paths, so if you use a different path separator in a search - path, you may get a mixture of PATH_SEPARATORs (from the core) and - alternate path separators (specified by users and placed into the - options database). - -----------------------------------------------------------------------------*/ - static error open(std::string const &path, std::uint32_t openflags, ptr &file, std::uint64_t &filesize); - - - /*----------------------------------------------------------------------------- - osd_file::openpty: create a new PTY pair - - Parameters: - - file - reference to an osd_file::ptr to receive the handle of the master - side of the newly-created PTY; this is only valid if the function - returns FILERR_NONE - - name - reference to string where slave filename will be stored - - Return value: - - a file_error describing any error that occurred while creating the - PTY, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - static error openpty(ptr &file, std::string &name); - - - /*----------------------------------------------------------------------------- - osd_file::~osd_file: close an open file - -----------------------------------------------------------------------------*/ - virtual ~osd_file() { } - - - /*----------------------------------------------------------------------------- - osd_file::read: read from an open file - - Parameters: - - buffer - pointer to memory that will receive the data read - - offset - offset within the file to read from - - length - number of bytes to read from the file - - actual - reference to a uint32_t to receive the number of bytes actually - read during the operation; valid only if the function returns - FILERR_NONE - - Return value: - - a file_error describing any error that occurred while reading - from the file, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - virtual error read(void *buffer, std::uint64_t offset, std::uint32_t length, std::uint32_t &actual) = 0; - - - /*----------------------------------------------------------------------------- - osd_file::write: write to an open file - - Parameters: - - buffer - pointer to memory that contains the data to write - - offset - offset within the file to write to - - length - number of bytes to write to the file - - actual - reference to a uint32_t to receive the number of bytes actually - written during the operation; valid only if the function returns - FILERR_NONE - - Return value: - - a file_error describing any error that occurred while writing to - the file, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - virtual error write(void const *buffer, std::uint64_t offset, std::uint32_t length, std::uint32_t &actual) = 0; - - - /*----------------------------------------------------------------------------- - osd_file::truncate: change the size of an open file - - Parameters: - -. offset - future size of the file - - Return value: - - a file_error describing any error that occurred while writing to - the file, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - virtual error truncate(std::uint64_t offset) = 0; - - - /*----------------------------------------------------------------------------- - osd_file::flush: flush file buffers - - Parameters: - - file - handle to a file previously opened via osd_open - - Return value: - - a file_error describing any error that occurred while flushing file - buffers, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - virtual error flush() = 0; - - - /*----------------------------------------------------------------------------- - osd_file::remove: deletes a file - - Parameters: - - filename - path to file to delete - - Return value: - - a file_error describing any error that occurred while deleting - the file, or FILERR_NONE if no error occurred - -----------------------------------------------------------------------------*/ - static error remove(std::string const &filename); -}; - - - -/*----------------------------------------------------------------------------- - osd_getenv: return pointer to environment variable - - Parameters: - - name - name of environment variable - - Return value: - - pointer to value ------------------------------------------------------------------------------*/ +/// \brief Get environment variable value +/// +/// \param [in] name Name of the environment variable as a +/// NUL-terminated string. +/// \return Pointer to environment variable value as a NUL-terminated +/// string if found, or nullptr if not found. const char *osd_getenv(const char *name); -/*----------------------------------------------------------------------------- - osd_getpid: gets process id - - Return value: - - process id ------------------------------------------------------------------------------*/ -int osd_getpid(); - -/*----------------------------------------------------------------------------- - osd_get_physical_drive_geometry: if the given path points to a physical - drive, return the geometry of that drive - - Parameters: - - filename - pointer to a path which might describe a physical drive - - cylinders - pointer to a uint32_t to receive the number of cylinders - of the physical drive - - heads - pointer to a uint32_t to receive the number of heads per - cylinder of the physical drive - - sectors - pointer to a uint32_t to receive the number of sectors per - cylinder of the physical drive - bps - pointer to a uint32_t to receive the number of bytes per sector - of the physical drive - - Return value: - - true if the filename points to a physical drive and if the values - pointed to by cylinders, heads, sectors, and bps are valid; false in - any other case ------------------------------------------------------------------------------*/ -bool osd_get_physical_drive_geometry(const char *filename, uint32_t *cylinders, uint32_t *heads, uint32_t *sectors, uint32_t *bps); +/// \brief Get current process ID +/// +/// \return The process ID of the current process. +int osd_getpid() noexcept; /*----------------------------------------------------------------------------- @@ -302,115 +60,6 @@ bool osd_get_physical_drive_geometry(const char *filename, uint32_t *cylinders, int osd_uchar_from_osdchar(char32_t *uchar, const char *osdchar, size_t count); -/*----------------------------------------------------------------------------- - osd_is_valid_filename_char: is the given character legal for filenames? - - Parameters: - - uchar - the character to check - - Return value: - - Whether this character is legal in a filename ------------------------------------------------------------------------------*/ - -bool osd_is_valid_filename_char(char32_t uchar); - - -/*----------------------------------------------------------------------------- - osd_is_valid_filepath_char: is the given character legal for paths? - - Parameters: - - uchar - the character to check - - Return value: - - Whether this character is legal in a file path ------------------------------------------------------------------------------*/ - -bool osd_is_valid_filepath_char(char32_t uchar); - - -/*************************************************************************** - DIRECTORY INTERFACES -***************************************************************************/ - -namespace osd -{ - // directory is an opaque type which represents an open directory - class directory - { - public: - typedef std::unique_ptr<directory> ptr; - - // osd::directory::entry contains basic information about a file when iterating through - // a directory - class entry - { - public: - enum class entry_type - { - NONE, - FILE, - DIR, - OTHER - }; - - const char * name; // name of the entry - entry_type type; // type of the entry - std::uint64_t size; // size of the entry - std::chrono::system_clock::time_point last_modified; // last modified time - }; - - // ----------------------------------------------------------------------------- - // osd::directory::open: open a directory for iteration - // - // Parameters: - // - // dirname - path to the directory in question - // - // Return value: - // - // upon success, this function should return an directory pointer - // which contains opaque data necessary to traverse the directory; on - // failure, this function should return nullptr - // ----------------------------------------------------------------------------- - static ptr open(std::string const &dirname); - - // ----------------------------------------------------------------------------- - // osd::directory::~directory: close an open directory - // ----------------------------------------------------------------------------- - virtual ~directory() { } - - // ----------------------------------------------------------------------------- - // osd::directory::read: return information about the next entry in the directory - // - // Return value: - // - // a constant pointer to an entry representing the current item - // in the directory, or nullptr, indicating that no more entries are - // present - // ----------------------------------------------------------------------------- - virtual const entry *read() = 0; - }; -}; - - -/*----------------------------------------------------------------------------- - osd_is_absolute_path: returns whether the specified path is absolute - - Parameters: - - path - the path in question - - Return value: - - non-zero if the path is absolute, zero otherwise ------------------------------------------------------------------------------*/ -bool osd_is_absolute_path(const std::string &path); - - /*************************************************************************** TIMING INTERFACES @@ -438,7 +87,7 @@ typedef uint64_t osd_ticks_t; accurate. It is ok if this call is not ultra-fast, since it is primarily used for once/frame synchronization. -----------------------------------------------------------------------------*/ -osd_ticks_t osd_ticks(void); +osd_ticks_t osd_ticks() noexcept; /*----------------------------------------------------------------------------- @@ -453,7 +102,7 @@ osd_ticks_t osd_ticks(void); an osd_ticks_t value which represents the number of ticks per second -----------------------------------------------------------------------------*/ -osd_ticks_t osd_ticks_per_second(void); +osd_ticks_t osd_ticks_per_second() noexcept; /*----------------------------------------------------------------------------- @@ -478,7 +127,9 @@ osd_ticks_t osd_ticks_per_second(void); sleep occurs for, the OSD layer should strive to sleep for less time than specified rather than sleeping too long. -----------------------------------------------------------------------------*/ -void osd_sleep(osd_ticks_t duration); +void osd_sleep(osd_ticks_t duration) noexcept; + + /*************************************************************************** WORK ITEM INTERFACES @@ -693,171 +344,37 @@ void osd_work_item_release(osd_work_item *item); MISCELLANEOUS INTERFACES ***************************************************************************/ -/*----------------------------------------------------------------------------- - osd_alloc_executable: allocate memory that can contain executable code - - Parameters: - - size - the number of bytes to allocate - - Return value: - - a pointer to the allocated memory - - Notes: - - On many systems, this call may acceptably map to malloc(). On systems - where pages are tagged with "no execute" privileges, it may be - necessary to perform some kind of special allocation to ensure that - code placed into this buffer can be executed. ------------------------------------------------------------------------------*/ -void *osd_alloc_executable(size_t size); - - -/*----------------------------------------------------------------------------- - osd_free_executable: free memory allocated by osd_alloc_executable - - Parameters: - - ptr - the pointer returned from osd_alloc_executable - - size - the number of bytes originally requested - - Return value: - - None ------------------------------------------------------------------------------*/ -void osd_free_executable(void *ptr, size_t size); - - -/*----------------------------------------------------------------------------- - osd_break_into_debugger: break into the hosting system's debugger if one - is attached - - Parameters: - - message - pointer to string to output to the debugger - - Return value: - - None. - - Notes: - - This function is called when an assertion or other important error - occurs. If a debugger is attached to the current process, it should - break into the debugger and display the given message. ------------------------------------------------------------------------------*/ +/// \brief Break into host debugger if attached +/// +/// This function is called when a fatal error occurs. If a debugger is +/// attached, it should break and display the specified message. +/// \param [in] message Message to output to the debugger as a +/// NUL-terminated string. void osd_break_into_debugger(const char *message); -/*----------------------------------------------------------------------------- - osd_get_clipboard_text: retrieves text from the clipboard ------------------------------------------------------------------------------*/ -std::string osd_get_clipboard_text(void); +/// \brief Get cache line size in bytes +/// +/// This function gets the host CPU's level 1 cache line size in bytes. +/// \return A pair consisting of an error condition and the cache line +/// size in bytes if successful. +std::pair<std::error_condition, unsigned> osd_get_cache_line_size() noexcept; -/*************************************************************************** - DIRECTORY INTERFACES -***************************************************************************/ - -/*----------------------------------------------------------------------------- - osd_stat: return a directory entry for a path - - Parameters: - path - path in question - - Return value: - - an allocated pointer to an osd::directory::entry representing - info on the path; even if the file does not exist. - ------------------------------------------------------------------------------*/ -std::unique_ptr<osd::directory::entry> osd_stat(std::string const &path); - -/*************************************************************************** - PATH INTERFACES -***************************************************************************/ - -/*----------------------------------------------------------------------------- - osd_get_full_path: retrieves the full path - - Parameters: - - path - the path in question - dst - reference to receive new path - - Return value: - - file error - ------------------------------------------------------------------------------*/ -osd_file::error osd_get_full_path(std::string &dst, std::string const &path); - - -/*************************************************************************** - MIDI I/O INTERFACES -***************************************************************************/ - -class osd_midi_device -{ -public: - virtual ~osd_midi_device() { } - // free result with osd_close_midi_channel() - virtual bool open_input(const char *devname) = 0; - // free result with osd_close_midi_channel() - virtual bool open_output(const char *devname) = 0; - virtual void close() = 0; - virtual bool poll() = 0; - virtual int read(uint8_t *pOut) = 0; - virtual void write(uint8_t data) = 0; -}; - -//FIXME: really needed here? -void osd_list_network_adapters(void); /*************************************************************************** UNCATEGORIZED INTERFACES ***************************************************************************/ /*----------------------------------------------------------------------------- - osd_get_volume_name: retrieves the volume name - - Parameters: - - idx - order number of volume - - Return value: - - pointer to volume name - ------------------------------------------------------------------------------*/ -const char *osd_get_volume_name(int idx); - -/*----------------------------------------------------------------------------- osd_subst_env: substitute environment variables with values Parameters: - dst - result pointer src - source string -----------------------------------------------------------------------------*/ -void osd_subst_env(std::string &dst,std::string const &src); - -/* ----- output management ----- */ - -// output channels -enum osd_output_channel -{ - OSD_OUTPUT_CHANNEL_ERROR, - OSD_OUTPUT_CHANNEL_WARNING, - OSD_OUTPUT_CHANNEL_INFO, - OSD_OUTPUT_CHANNEL_DEBUG, - OSD_OUTPUT_CHANNEL_VERBOSE, - OSD_OUTPUT_CHANNEL_LOG, - OSD_OUTPUT_CHANNEL_COUNT -}; +std::string osd_subst_env(std::string_view src); class osd_gpu { @@ -1010,33 +527,118 @@ public: virtual void unbind_buffer(vertex_buffer_interface *vb) = 0; }; + +/// \defgroup osd_printf Diagnostic output functions +/// \{ + +// output channels +enum osd_output_channel +{ + OSD_OUTPUT_CHANNEL_ERROR, + OSD_OUTPUT_CHANNEL_WARNING, + OSD_OUTPUT_CHANNEL_INFO, + OSD_OUTPUT_CHANNEL_DEBUG, + OSD_OUTPUT_CHANNEL_VERBOSE, + OSD_OUTPUT_CHANNEL_LOG, + OSD_OUTPUT_CHANNEL_COUNT +}; + class osd_output { public: - osd_output() : m_chain(nullptr) { } + osd_output() { } virtual ~osd_output() { } - virtual void output_callback(osd_output_channel channel, const char *msg, va_list args) = 0; + virtual void output_callback(osd_output_channel channel, util::format_argument_pack<char> const &args) = 0; static void push(osd_output *delegate); static void pop(osd_output *delegate); + protected: - void chain_output(osd_output_channel channel, const char *msg, va_list args) const + void chain_output(osd_output_channel channel, util::format_argument_pack<char> const &args) const { - if (m_chain != nullptr) - m_chain->output_callback(channel, msg, args); + if (m_chain) + m_chain->output_callback(channel, args); } + private: - osd_output *m_chain; + osd_output *m_chain = nullptr; }; -/* calls to be used by the code */ -void CLIB_DECL osd_printf_error(const char *format, ...) ATTR_PRINTF(1,2); -void CLIB_DECL osd_printf_warning(const char *format, ...) ATTR_PRINTF(1,2); -void CLIB_DECL osd_printf_info(const char *format, ...) ATTR_PRINTF(1,2); -void CLIB_DECL osd_printf_verbose(const char *format, ...) ATTR_PRINTF(1,2); -void CLIB_DECL osd_printf_debug(const char *format, ...) ATTR_PRINTF(1,2); +void osd_vprintf_error(util::format_argument_pack<char> const &args); +void osd_vprintf_warning(util::format_argument_pack<char> const &args); +void osd_vprintf_info(util::format_argument_pack<char> const &args); +void osd_vprintf_verbose(util::format_argument_pack<char> const &args); +void osd_vprintf_debug(util::format_argument_pack<char> const &args); + +/// \brief Print error message +/// +/// By default, error messages are sent to standard error. The relaxed +/// format rules used by util::string_format apply. +/// \param [in] fmt Message format string. +/// \param [in] args Optional message format arguments. +/// \sa util::string_format +template <typename Format, typename... Params> void osd_printf_error(Format &&fmt, Params &&...args) +{ + return osd_vprintf_error(util::make_format_argument_pack(std::forward<Format>(fmt), std::forward<Params>(args)...)); +} + +/// \brief Print warning message +/// +/// By default, warning messages are sent to standard error. The +/// relaxed format rules used by util::string_format apply. +/// \param [in] fmt Message format string. +/// \param [in] args Optional message format arguments. +/// \sa util::string_format +template <typename Format, typename... Params> void osd_printf_warning(Format &&fmt, Params &&...args) +{ + return osd_vprintf_warning(util::make_format_argument_pack(std::forward<Format>(fmt), std::forward<Params>(args)...)); +} + +/// \brief Print informational message +/// +/// By default, informational messages are sent to standard output. +/// The relaxed format rules used by util::string_format apply. +/// \param [in] fmt Message format string. +/// \param [in] args Optional message format arguments. +/// \sa util::string_format +template <typename Format, typename... Params> void osd_printf_info(Format &&fmt, Params &&...args) +{ + return osd_vprintf_info(util::make_format_argument_pack(std::forward<Format>(fmt), std::forward<Params>(args)...)); +} + +/// \brief Print verbose diagnostic message +/// +/// Verbose diagnostic messages are disabled by default. If enabled, +/// they are sent to standard output by default. The relaxed format +/// rules used by util::string_format apply. Note that the format +/// string and arguments will always be evaluated, even if verbose +/// diagnostic messages are disabled. +/// \param [in] fmt Message format string. +/// \param [in] args Optional message format arguments. +/// \sa util::string_format +template <typename Format, typename... Params> void osd_printf_verbose(Format &&fmt, Params &&...args) +{ + return osd_vprintf_verbose(util::make_format_argument_pack(std::forward<Format>(fmt), std::forward<Params>(args)...)); +} + +/// \brief Print debug message +/// +/// By default, debug messages are sent to standard output for debug +/// builds only. The relaxed format rules used by util::string_format +/// apply. Note that the format string and arguments will always be +/// evaluated, even if debug messages are disabled. +/// \param [in] fmt Message format string. +/// \param [in] args Optional message format arguments. +/// \sa util::string_format +template <typename Format, typename... Params> void osd_printf_debug(Format &&fmt, Params &&...args) +{ + return osd_vprintf_debug(util::make_format_argument_pack(std::forward<Format>(fmt), std::forward<Params>(args)...)); +} + +/// \} + // returns command line arguments as an std::vector<std::string> in UTF-8 std::vector<std::string> osd_get_command_line(int argc, char *argv[]); |