summaryrefslogtreecommitdiffstatshomepage
path: root/src/emu/device.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/emu/device.h')
-rw-r--r--src/emu/device.h120
1 files changed, 102 insertions, 18 deletions
diff --git a/src/emu/device.h b/src/emu/device.h
index 05fa523b6fd..cab07888d35 100644
--- a/src/emu/device.h
+++ b/src/emu/device.h
@@ -335,42 +335,126 @@ template <
emu::detail::device_feature::type Imperfect>
constexpr auto driver_device_creator = &emu::detail::driver_tag_func<DriverClass, ShortName, FullName, Source, Unemulated, Imperfect>;
+
+/// \addtogroup machinedef
+/// \{
+
+/// \brief Declare a device type
+///
+/// Declares a device type where the exposed device class is in the
+/// global namespace. Must be used in the global namespace.
+///
+/// In addition to declaring the device type itself, a forward
+/// declaration for the exposed device class is generated, and automatic
+/// instantiation of device finder templates for the exposed device
+/// class is suppressed.
+/// \param Type The device type name (an identifier). By convention,
+/// these start with an uppercase letter and consist only of uppercase
+/// letters and underscores.
+/// \param Class The exposed device class name. Must be the device
+/// implementation class, or a public base of it, and must be derived
+/// from #device_t.
+/// \sa DECLARE_DEVICE_TYPE_NS DEFINE_DEVICE_TYPE
+/// DEFINE_DEVICE_TYPE_PRIVATE
#define DECLARE_DEVICE_TYPE(Type, Class) \
class Class; \
- extern emu::detail::device_type_impl<Class> const &Type; \
+ extern emu::detail::device_type_impl<Class> const Type; \
extern template class device_finder<Class, false>; \
extern template class device_finder<Class, true>;
+
+/// \brief Declare a device type for a class in a namespace
+///
+/// Declares a device type where the exposed device class is not in the
+/// global namespace. Must be used in the global namespace.
+///
+/// In addition to declaring the device type itself, a forward
+/// declaration for the exposed device class is generated, and automatic
+/// instantiation of device finder templates for the exposed device
+/// class is suppressed.
+/// \param Type The device type name (an identifier). By convention,
+/// these start with an uppercase letter and consist only of uppercase
+/// letters and underscores.
+/// \param Namespace The fully qualified name of the namespace
+/// containing the exposed device class.
+/// \param Class The exposed device class name, without namespace
+/// qualifiers. Must be the device implementation class, or a public
+/// base of it, and must be derived from #device_t.
+/// \sa DECLARE_DEVICE_TYPE DEFINE_DEVICE_TYPE
+/// DEFINE_DEVICE_TYPE_PRIVATE
#define DECLARE_DEVICE_TYPE_NS(Type, Namespace, Class) \
namespace Namespace { class Class; } \
- extern emu::detail::device_type_impl<Namespace::Class> const &Type; \
+ extern emu::detail::device_type_impl<Namespace::Class> const Type; \
extern template class device_finder<Namespace::Class, false>; \
extern template class device_finder<Namespace::Class, true>;
+
+/// \brief Define a device type
+///
+/// Defines a device type where the exposed device class is the same as
+/// the device implementation class. Must be used in the global
+/// namespace.
+///
+/// As well as defining the device type, device finder templates are
+/// instantiated for the device class.
+/// \param Type The device type name (an identifier). By convention,
+/// these start with an uppercase letter and consist only of uppercase
+/// letters and underscores.
+/// \param Class The device implementation class name. Must be the same
+/// as the exposed device class, and must be derived from #device_t.
+/// \param ShortName The short name of the device, used for
+/// identification, and in filesystem paths for assets and data. Must
+/// be a string no longer than thirty-two characters, containing only
+/// ASCII lowercase letters, digits and underscores. Must be globally
+/// unique across systems and devices.
+/// \param FullName Display name for the device. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \sa DECLARE_DEVICE_TYPE DECLARE_DEVICE_TYPE_NS
+/// DEFINE_DEVICE_TYPE_PRIVATE
#define DEFINE_DEVICE_TYPE(Type, Class, ShortName, FullName) \
namespace { \
- struct Class##_device_traits { static constexpr char const shortname[] = ShortName, fullname[] = FullName, source[] = __FILE__; }; \
- constexpr char const Class##_device_traits::shortname[], Class##_device_traits::fullname[], Class##_device_traits::source[]; \
+ struct Type##_device_traits { static constexpr char const shortname[] = ShortName, fullname[] = FullName, source[] = __FILE__; }; \
+ constexpr char const Type##_device_traits::shortname[], Type##_device_traits::fullname[], Type##_device_traits::source[]; \
} \
- emu::detail::device_type_impl<Class> const &Type = device_creator<Class, (Class##_device_traits::shortname), (Class##_device_traits::fullname), (Class##_device_traits::source)>; \
+ emu::detail::device_type_impl<Class> const Type = device_creator<Class, (Type##_device_traits::shortname), (Type##_device_traits::fullname), (Type##_device_traits::source)>; \
template class device_finder<Class, false>; \
template class device_finder<Class, true>;
+
+/// \brief Define a device type with a private implementation class
+///
+/// Defines a device type where the exposed device class is a base of
+/// the device implementation class. Must be used in the global
+/// namespace.
+///
+/// Device finder templates are not instantiated for the exposed device
+/// class. This must be done explicitly in a single location for the
+/// project.
+/// \param Type The device type name (an identifier). By convention,
+/// these start with an uppercase letter and consist only of uppercase
+/// letters and underscores.
+/// \param Base The fully-qualified exposed device class name. Must be
+/// a public base of the device implementation class, and must be
+/// derived from #device_t.
+/// \param Class The fully-qualified device implementation class name.
+/// Must be derived from the exposed device class, and indirectly from
+/// #device_t.
+/// \param ShortName The short name of the device, used for
+/// identification, and in filesystem paths for assets and data. Must
+/// be a string no longer than thirty-two characters, containing only
+/// ASCII lowercase letters, digits and underscores. Must be globally
+/// unique across systems and devices.
+/// \param FullName Display name for the device. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \sa DECLARE_DEVICE_TYPE DECLARE_DEVICE_TYPE_NS DEFINE_DEVICE_TYPE
#define DEFINE_DEVICE_TYPE_PRIVATE(Type, Base, Class, ShortName, FullName) \
namespace { \
- struct Class##_device_traits { static constexpr char const shortname[] = ShortName, fullname[] = FullName, source[] = __FILE__; }; \
- constexpr char const Class##_device_traits::shortname[], Class##_device_traits::fullname[], Class##_device_traits::source[]; \
+ struct Type##_device_traits { static constexpr char const shortname[] = ShortName, fullname[] = FullName, source[] = __FILE__; }; \
+ constexpr char const Type##_device_traits::shortname[], Type##_device_traits::fullname[], Type##_device_traits::source[]; \
} \
- emu::detail::device_type_impl<Base> const &Type = device_creator<Class, (Class##_device_traits::shortname), (Class##_device_traits::fullname), (Class##_device_traits::source)>;
+ emu::detail::device_type_impl<Base> const Type = device_creator<Class, (Type##_device_traits::shortname), (Type##_device_traits::fullname), (Type##_device_traits::source)>;
-#define DEFINE_DEVICE_TYPE_NS(Type, Namespace, Class, ShortName, FullName) \
- namespace { \
- struct Class##_device_traits { static constexpr char const shortname[] = ShortName, fullname[] = FullName, source[] = __FILE__; }; \
- constexpr char const Class##_device_traits::shortname[], Class##_device_traits::fullname[], Class##_device_traits::source[]; \
- } \
- emu::detail::device_type_impl<Namespace::Class> const &Type = device_creator<Namespace::Class, (Class##_device_traits::shortname), (Class##_device_traits::fullname), (Class##_device_traits::source)>; \
- template class device_finder<Namespace::Class, false>; \
- template class device_finder<Namespace::Class, true>;
+/// \}
// exception classes
@@ -526,8 +610,8 @@ public:
///
/// Implement this member in a derived class to declare the parent
/// device type for the purpose of searching for ROMs. Only one
- /// level is allowed. It is an error if the parent device type itself
- /// declares a parent device type.
+ /// level is allowed. It is an error if the parent device type
+ /// itself declares a parent device type.
/// \return Pointer to parent device type, or nullptr.
static auto parent_rom_device_type() { return nullptr; }