summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatarGravatar balr0g <balrog032@gmail.com>2016-03-16 16:18:42 -0400
committerGravatarGravatar balr0g <balrog032@gmail.com>2016-03-16 19:30:33 -0400
commit23db5c6898e65d79d43a35d23ca07cd409dee3da (patch) (github)
tree9c892bac5c0212aa5ef3ad479f384e839dc8f68c
parent157de7d935dad7ea732088f0f48d92c925b3bc37 (diff)
downloadmame-doxygen.tar.bz2
mame-doxygen.zip
documentation wipdoxygen
-rw-r--r--doxygen/doxygen.config10
-rw-r--r--src/emu/attotime.h95
-rw-r--r--src/emu/emu.h21
-rw-r--r--src/emu/mconfig.h113
4 files changed, 151 insertions, 88 deletions
diff --git a/doxygen/doxygen.config b/doxygen/doxygen.config
index 9cdc7792934..d81fc061cf3 100644
--- a/doxygen/doxygen.config
+++ b/doxygen/doxygen.config
@@ -447,7 +447,7 @@ EXTRACT_ANON_NSPACES = NO
# section is generated. This option has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
-HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy. If set
@@ -455,7 +455,7 @@ HIDE_UNDOC_MEMBERS = NO
# no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
-HIDE_UNDOC_CLASSES = NO
+HIDE_UNDOC_CLASSES = YES
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
# (class|struct|union) declarations. If set to NO these declarations will be
@@ -733,7 +733,7 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.
-INPUT = doxygen/README.md src/emu src/osd src/lib
+INPUT = doxygen/README.md src/emu src/lib/util #src/osd src/lib/util
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -759,7 +759,7 @@ FILE_PATTERNS = *.h *.cpp *.mm *.md
# be searched for input files as well.
# The default value is: NO.
-RECURSIVE = YES
+RECURSIVE = NO
# The EXCLUDE tag can be used to specify files and/or directories that should be
# excluded from the INPUT source files. This way you can easily exclude a
@@ -2147,7 +2147,7 @@ CALL_GRAPH = NO
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
-CALLER_GRAPH = NO
+CALLER_GRAPH = YES
# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
# hierarchy of all classes instead of a textual one.
diff --git a/src/emu/attotime.h b/src/emu/attotime.h
index a0915ae07f2..14999ed1b59 100644
--- a/src/emu/attotime.h
+++ b/src/emu/attotime.h
@@ -1,34 +1,34 @@
// license:BSD-3-Clause
// copyright-holders:Aaron Giles
-/***************************************************************************
-
- attotime.h
-
- Support functions for working with attotime data.
-
-****************************************************************************
-
- Attotime is an attosecond-accurate timing system implemented as
- 96-bit integers.
-
- 1 second = 1e0 seconds
- 1 millisecond = 1e-3 seconds
- 1 microsecond = 1e-6 seconds
- 1 nanosecond = 1e-9 seconds
- 1 picosecond = 1e-12 seconds
- 1 femtosecond = 1e-15 seconds
- 1 attosecond = 1e-18 seconds
-
- This may seem insanely accurate, but it has its uses when multiple
- clocks in the system are run by independent crystals. It is also
- useful to compute the attotime for something small, say 1 clock tick,
- and still have it be accurate and useful for scaling.
-
- Attotime consists of a 32-bit seconds count and a 64-bit attoseconds
- count. Because the lower bits are kept as attoseconds and not as a
- full 64-bit value, there is headroom to make some operations simpler.
-
-***************************************************************************/
+/**************************************************************************/
+/**
+ * @file attotime.h
+ * Support functions for working with attotime data.
+ * @defgroup ATTOTIME Support functions for working with attotime data
+ * @{
+ * .
+ * @class attotime
+ * Attotime is an attosecond-accurate timing system implemented as
+ * 96-bit integers.
+ *
+ * 1 second = 1e0 seconds
+ * 1 millisecond = 1e-3 seconds
+ * 1 microsecond = 1e-6 seconds
+ * 1 nanosecond = 1e-9 seconds
+ * 1 picosecond = 1e-12 seconds
+ * 1 femtosecond = 1e-15 seconds
+ * 1 attosecond = 1e-18 seconds
+ *
+ * This may seem insanely accurate, but it has its uses when multiple
+ * clocks in the system are run by independent crystals. It is also
+ * useful to compute the attotime for something small, say 1 clock tick,
+ * and still have it be accurate and useful for scaling.
+ *
+ * Attotime consists of a 32-bit seconds count and a 64-bit attoseconds
+ * count. Because the lower bits are kept as attoseconds and not as a
+ * full 64-bit value, there is headroom to make some operations simpler.
+ */
+/**************************************************************************/
#pragma once
@@ -54,7 +54,7 @@ const attoseconds_t ATTOSECONDS_PER_MILLISECOND = ATTOSECONDS_PER_SECOND / 1000;
const attoseconds_t ATTOSECONDS_PER_MICROSECOND = ATTOSECONDS_PER_SECOND / 1000000;
const attoseconds_t ATTOSECONDS_PER_NANOSECOND = ATTOSECONDS_PER_SECOND / 1000000000;
-const seconds_t ATTOTIME_MAX_SECONDS = 1000000000;
+const seconds_t ATTOTIME_MAX_SECONDS = 1000000000; /**< Cutoff value in seconds; anything higher than this is converted to "never" */
@@ -63,17 +63,25 @@ const seconds_t ATTOTIME_MAX_SECONDS = 1000000000;
//**************************************************************************
// convert between a double and attoseconds
+/** Convert from attoseconds to seconds (as a double) */
#define ATTOSECONDS_TO_DOUBLE(x) ((double)(x) * 1e-18)
+/** Convert from seconds (as a double) to attoseconds */
#define DOUBLE_TO_ATTOSECONDS(x) ((attoseconds_t)((x) * 1e18))
// convert between hertz (as a double) and attoseconds
+/** Convert from attoseconds to hertz (as a double) */
#define ATTOSECONDS_TO_HZ(x) ((double)ATTOSECONDS_PER_SECOND / (double)(x))
+/** Convert from hertz (as a double) to attoseconds */
#define HZ_TO_ATTOSECONDS(x) ((attoseconds_t)(ATTOSECONDS_PER_SECOND / (x)))
// macros for converting other seconds types to attoseconds
+/** Convert from seconds (as a double) to attoseconds */
#define ATTOSECONDS_IN_SEC(x) ((attoseconds_t)(x) * ATTOSECONDS_PER_SECOND)
+/** Convert from milliseconds (as a double) to attoseconds */
#define ATTOSECONDS_IN_MSEC(x) ((attoseconds_t)(x) * ATTOSECONDS_PER_MILLISECOND)
+/** Convert from microseconds (as a double) to attoseconds */
#define ATTOSECONDS_IN_USEC(x) ((attoseconds_t)(x) * ATTOSECONDS_PER_MICROSECOND)
+/** Convert from nanoseconds (as a double) to attoseconds */
#define ATTOSECONDS_IN_NSEC(x) ((attoseconds_t)(x) * ATTOSECONDS_PER_NANOSECOND)
@@ -82,24 +90,27 @@ const seconds_t ATTOTIME_MAX_SECONDS = 1000000000;
// TYPE DEFINITIONS
//***************************************************************************/
-// the attotime structure itself
+// class is documented above
class attotime
{
public:
// construction/destruction
+ /** Constructs with value of zero. */
attotime()
: m_seconds(0),
m_attoseconds(0) { }
+ /** Constructs with @p secs seconds and @p attos attosecons. */
attotime(seconds_t secs, attoseconds_t attos)
: m_seconds(secs),
m_attoseconds(attos) { }
+ /** Copy constructor */
attotime(const attotime& that)
: m_seconds(that.m_seconds),
m_attoseconds(that.m_attoseconds) { }
- // assignment
+ /** Assignment */
attotime& operator=(const attotime& that)
{
this->m_seconds = that.m_seconds;
@@ -107,14 +118,17 @@ public:
return *this;
}
- // queries
+ /** Test if value is zero */
bool is_zero() const { return (m_seconds == 0 && m_attoseconds == 0); }
+ /** Test if value is above @ref ATTOTIME_MAX_SECONDS */
bool is_never() const { return (m_seconds >= ATTOTIME_MAX_SECONDS); }
- // conversion to other forms
+ /** Convert to a double */
double as_double() const { return double(m_seconds) + ATTOSECONDS_TO_DOUBLE(m_attoseconds); }
attoseconds_t as_attoseconds() const;
+ /** Convert to ticks based on @p frequency */
UINT64 as_ticks(UINT32 frequency) const;
+ /** Convert to string using @p precision */
const char *as_string(int precision = 9) const;
attoseconds_t attoseconds() const { return m_attoseconds; }
@@ -330,10 +344,10 @@ inline attotime min(const attotime &left, const attotime &right)
}
-//-------------------------------------------------
-// max - return the maximum of two attotimes
-//-------------------------------------------------
+/** Calculate the maximum
+ @return maximum of @p left and @p right
+*/
inline attotime max(const attotime &left, const attotime &right)
{
if (left.m_seconds > right.m_seconds)
@@ -346,11 +360,7 @@ inline attotime max(const attotime &left, const attotime &right)
}
-//-------------------------------------------------
-// as_attoseconds - convert to an attoseconds
-// value, clamping to +/- 1 second
-//-------------------------------------------------
-
+/** convert to an attoseconds value, clamping to +/- 1 second */
inline attoseconds_t attotime::as_attoseconds() const
{
// positive values between 0 and 1 second
@@ -416,3 +426,4 @@ inline attotime attotime::from_double(double _time)
#endif // __ATTOTIME_H__
+/** @} */
diff --git a/src/emu/emu.h b/src/emu/emu.h
index e978bbe44d5..f90eed8a054 100644
--- a/src/emu/emu.h
+++ b/src/emu/emu.h
@@ -1,8 +1,8 @@
// license:BSD-3-Clause
// copyright-holders:Aaron Giles
-/***************************************************************************
-
- emu.h
+/**************************************************************************/
+/**
+ @file emu.h
Core header file to be included by most files.
@@ -12,8 +12,8 @@
If you find yourself needing something outside of this file in a
driver or device, think carefully about what you are doing.
-
-***************************************************************************/
+*/
+/**************************************************************************/
#ifndef __EMU_H__
#define __EMU_H__
@@ -49,9 +49,14 @@
#include "romload.h"
#include "save.h"
-// define machine_config_constructor here due to circular dependency
-// between devices and the machine config
-class machine_config;
+
+class machine_config; // forward declaration needed for machine_config_constructor
+
+/** Represents the constructor for a machine_config object.
+ * Use MACHINE_CONFIG_NAME(_name) to formulate the correct value.
+ * Defined in emu.h due to circular dependency between devices and the machine config.
+ * @ingroup MACHINE_CONFIG
+ */
typedef device_t * (*machine_config_constructor)(machine_config &config, device_t *owner, device_t *device);
// I/O
diff --git a/src/emu/mconfig.h b/src/emu/mconfig.h
index 4fb118ca1c5..a7a86f811a8 100644
--- a/src/emu/mconfig.h
+++ b/src/emu/mconfig.h
@@ -3,6 +3,9 @@
/***************************************************************************/
/**
* @file mconfig.h
+ * @brief Core machine configuration macros and functions.
+ * @attention Don't include this file directly, use emu.h instead.
+ *
* @defgroup MACHINE_CONFIG Machine configuration macros and functions
* @{
*/
@@ -38,7 +41,11 @@ class screen_device;
// ======================> machine_config
-// machine configuration definition
+/** @brief Machine configuration definition. Should not be instantiated directly.
+ This class represents sub-device configuration for a machine/device.
+ This class is instantiated through @ref MACHINE_CONFIG_STANDALONE "MACHINE_" macros.
+ The configuration is built up using @ref MCFG_CORE "MCFG_" macros.
+*/
class machine_config
{
DISABLE_COPYING(machine_config);
@@ -59,14 +66,14 @@ public:
template<class _DeviceClass> inline _DeviceClass *device(const char *tag) const { return downcast<_DeviceClass *>(device(tag)); }
// public state
- attotime m_minimum_quantum; // minimum scheduling quantum
- std::string m_perfect_cpu_quantum; // tag of CPU to use for "perfect" scheduling
- INT32 m_watchdog_vblank_count; // number of VBLANKs until the watchdog kills us
- attotime m_watchdog_time; // length of time until the watchdog kills us
- bool m_force_no_drc; // whether or not to force DRC off
+ attotime m_minimum_quantum; //! minimum scheduling quantum
+ std::string m_perfect_cpu_quantum; //! tag of CPU to use for "perfect" scheduling
+ INT32 m_watchdog_vblank_count; //! number of VBLANKs until the watchdog kills us
+ attotime m_watchdog_time; //! length of time until the watchdog kills us
+ bool m_force_no_drc; //! whether or not to force DRC off
// other parameters
- const char * m_default_layout; // default layout for this machine
+ const char * m_default_layout; //! default layout for this machine
// helpers during configuration; not for general use
device_t *device_add(device_t *owner, const char *tag, device_type type, UINT32 clock);
@@ -81,22 +88,34 @@ private:
std::unique_ptr<device_t> m_root_device;
};
-
//*************************************************************************/
-/** @name Machine config start/end macros */
+/** @anchor MACHINE_CONFIG_STANDALONE
+ * @name Standalone machine config macros*/
//*************************************************************************/
/**
- @def MACHINE_CONFIG_NAME(_name)
- Returns the internal name for the machine config.
+ Returns the internal name for the machine_config.
@param _name name of desired config
@hideinitializer
*/
#define MACHINE_CONFIG_NAME(_name) construct_machine_config_##_name
/**
- @def MACHINE_CONFIG_START(_name, _class)
- Begins a new machine config.
+References an external machine_config.
+@param _name name of the machine_config to reference
+@hideinitializer
+*/
+#define MACHINE_CONFIG_EXTERN(_name) \
+ extern device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device)
+
+//*************************************************************************/
+/** @anchor MACHINE_CONFIG_BEGIN_END
+ * @name Machine config start/end macros
+ */
+//*************************************************************************/
+
+/**
+ Begins a new machine_config.
@param _name name of this config
@param _class driver_device class for this config
@hideinitializer
@@ -109,7 +128,6 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
if (owner == NULL) owner = config.device_add(NULL, "root", &driver_device_creator<_class>, 0);
/**
- @def MACHINE_CONFIG_FRAGMENT(_name)
Begins a partial machine_config that can only be included in another "root" machine_config. This is also used for machine_configs that are specified as part of a device.
@param _name name of this config fragment
@hideinitializer
@@ -122,7 +140,6 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
assert(owner != NULL);
/**
- @def MACHINE_CONFIG_DERIVED(_name, _base)
Begins a machine_config that is derived from another machine_config.
@param _name name of this config
@param _base name of the parent config
@@ -137,7 +154,6 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
assert(owner != NULL);
/**
-@def MACHINE_CONFIG_DERIVED_CLASS(_name, _base, _class)
Begins a machine_config that is derived from another machine_config that can specify an alternate driver_device class
@param _name name of this config
@param _base name of the parent config
@@ -153,7 +169,6 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
owner = MACHINE_CONFIG_NAME(_base)(config, owner, device);
/**
-@def MACHINE_CONFIG_END
Ends a machine_config.
@hideinitializer
*/
@@ -161,41 +176,73 @@ Ends a machine_config.
return owner; \
}
+
//*************************************************************************/
-/** @name Standalone machine config macros */
+/** @anchor MCFG_CORE
+ * @name Core machine config parameters
+ */
//*************************************************************************/
/**
-@def MACHINE_CONFIG_EXTERN(_name)
-References an external machine config.
-@param _name Name of the machine config to reference
+Imports a machine_config fragment from another driver
+@param _name config fragment to import into this config
@hideinitializer
*/
-#define MACHINE_CONFIG_EXTERN(_name) \
- extern device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device)
-
-//*************************************************************************/
-/** @name Core machine config options */
-//*************************************************************************/
-
-// importing data from other machine drivers
#define MCFG_FRAGMENT_ADD(_name) \
MACHINE_CONFIG_NAME(_name)(config, owner, device);
-// scheduling parameters
+//*************************************************************************/
+/** @anchor MCFG_SCHED
+ * @name Scheduling parameters
+ */
+//*************************************************************************/
+
+/**
+Specifies the quantum frequency for this config.
+This specifies how frequently the device defined by the config is updated.
+@param _time @ref attotime object representing the quantum frequency
+@hideinitializer
+*/
#define MCFG_QUANTUM_TIME(_time) \
config.m_minimum_quantum = _time;
+/**
+Specifies the quantum frequency for this config to be perfect for a specific CPU.
+@param _cputag tag string indicating the CPU to use
+@hideinitializer
+*/
#define MCFG_QUANTUM_PERFECT_CPU(_cputag) \
config.m_perfect_cpu_quantum = owner->subtag(_cputag);
-// recompilation parameters
+//*************************************************************************/
+/** @anchor MCFG_DRC
+ * @name Recompilation parameters
+ */
+//*************************************************************************/
+/**
+Disables DRC for this config.
+@hideinitializer
+*/
#define MCFG_FORCE_NO_DRC() \
config.m_force_no_drc = true;
-// watchdog configuration
+//*************************************************************************/
+/** @anchor MCFG_WATCHDOG
+* @name Watchdog configuration parameters
+*/
+//*************************************************************************/
+/**
+Configure the watchdog to fire at a specific vblank interval.
+@param _count vblank interval
+@hideinitializer
+*/
#define MCFG_WATCHDOG_VBLANK_INIT(_count) \
config.m_watchdog_vblank_count = _count;
+/**
+Configure the watchdog to fire at a specific time interval.
+@param _time @ref attotime object representing the interval
+@hideinitializer
+*/
#define MCFG_WATCHDOG_TIME_INIT(_time) \
config.m_watchdog_time = _time;
@@ -214,4 +261,4 @@ References an external machine config.
device = config.device_find(owner, _tag);
#endif /* __MCONFIG_H__ */
- /** @} */
+/** @} */