+ /* struct retro_perf_callback * --
+ * Gets an interface for performance counters. This is useful
+ * for performance logging in a cross-platform way and for detecting
+ * architecture-specific features, such as SIMD support.
+ */
+#define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29
+ /* struct retro_location_callback * --
+ * Gets access to the location interface.
+ * The purpose of this interface is to be able to retrieve
+ * location-based information from the host device,
+ * such as current latitude / longitude.
+ */
+#define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30
+ /* const char ** --
+ * Returns the "content" directory of the frontend.
+ * This directory can be used to store specific assets that the
+ * core relies upon, such as art assets,
+ * input data, etc etc.
+ * The returned value can be NULL.
+ * If so, no such directory is defined,
+ * and it's up to the implementation to find a suitable directory.
+ */
+#define RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY 31
+ /* const char ** --
+ * Returns the "save" directory of the frontend.
+ * This directory can be used to store SRAM, memory cards,
+ * high scores, etc, if the libretro core
+ * cannot use the regular memory interface (retro_get_memory_data()).
+ *
+ * NOTE: libretro cores used to check GET_SYSTEM_DIRECTORY for
+ * similar things before.
+ * They should still check GET_SYSTEM_DIRECTORY if they want to
+ * be backwards compatible.
+ * The path here can be NULL. It should only be non-NULL if the
+ * frontend user has set a specific save path.
+ */
+#define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32
+ /* const struct retro_system_av_info * --
+ * Sets a new av_info structure. This can only be called from
+ * within retro_run().
+ * This should *only* be used if the core is completely altering the
+ * internal resolutions, aspect ratios, timings, sampling rate, etc.
+ * Calling this can require a full reinitialization of video/audio
+ * drivers in the frontend,
+ *
+ * so it is important to call it very sparingly, and usually only with
+ * the users explicit consent.
+ * An eventual driver reinitialize will happen so that video and
+ * audio callbacks
+ * happening after this call within the same retro_run() call will
+ * target the newly initialized driver.
+ *
+ * This callback makes it possible to support configurable resolutions
+ * in games, which can be useful to
+ * avoid setting the "worst case" in max_width/max_height.
+ *
+ * ***HIGHLY RECOMMENDED*** Do not call this callback every time
+ * resolution changes in an emulator core if it's
+ * expected to be a temporary change, for the reasons of possible
+ * driver reinitialization.
+ * This call is not a free pass for not trying to provide
+ * correct values in retro_get_system_av_info(). If you need to change
+ * things like aspect ratio or nominal width/height,
+ * use RETRO_ENVIRONMENT_SET_GEOMETRY, which is a softer variant
+ * of SET_SYSTEM_AV_INFO.
+ *
+ * If this returns false, the frontend does not acknowledge a
+ * changed av_info struct.
+ */
+#define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33
+ /* const struct retro_get_proc_address_interface * --
+ * Allows a libretro core to announce support for the
+ * get_proc_address() interface.
+ * This interface allows for a standard way to extend libretro where
+ * use of environment calls are too indirect,
+ * e.g. for cases where the frontend wants to call directly into the core.
+ *
+ * If a core wants to expose this interface, SET_PROC_ADDRESS_CALLBACK
+ * **MUST** be called from within retro_set_environment().
+ */
+#define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34
+ /* const struct retro_subsystem_info * --
+ * This environment call introduces the concept of libretro "subsystems".
+ * A subsystem is a variant of a libretro core which supports
+ * different kinds of games.
+ * The purpose of this is to support e.g. emulators which might
+ * have special needs, e.g. Super Nintendo's Super GameBoy, Sufami Turbo.
+ * It can also be used to pick among subsystems in an explicit way
+ * if the libretro implementation is a multi-system emulator itself.
+ *
+ * Loading a game via a subsystem is done with retro_load_game_special(),
+ * and this environment call allows a libretro core to expose which
+ * subsystems are supported for use with retro_load_game_special().
+ * A core passes an array of retro_game_special_info which is terminated
+ * with a zeroed out retro_game_special_info struct.
+ *
+ * If a core wants to use this functionality, SET_SUBSYSTEM_INFO
+ * **MUST** be called from within retro_set_environment().
+ */
+#define RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 35
+ /* const struct retro_controller_info * --
+ * This environment call lets a libretro core tell the frontend
+ * which controller types are recognized in calls to
+ * retro_set_controller_port_device().
+ *
+ * Some emulators such as Super Nintendo
+ * support multiple lightgun types which must be specifically
+ * selected from.
+ * It is therefore sometimes necessary for a frontend to be able
+ * to tell the core about a special kind of input device which is
+ * not covered by the libretro input API.
+ *
+ * In order for a frontend to understand the workings of an input device,
+ * it must be a specialized type
+ * of the generic device types already defined in the libretro API.
+ *
+ * Which devices are supported can vary per input port.
+ * The core must pass an array of const struct retro_controller_info which
+ * is terminated with a blanked out struct. Each element of the struct
+ * corresponds to an ascending port index to
+ * retro_set_controller_port_device().
+ * Even if special device types are set in the libretro core,
+ * libretro should only poll input based on the base input device types.
+ */
+#define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL)
+ /* const struct retro_memory_map * --
+ * This environment call lets a libretro core tell the frontend
+ * about the memory maps this core emulates.
+ * This can be used to implement, for example, cheats in a core-agnostic way.
+ *
+ * Should only be used by emulators; it doesn't make much sense for
+ * anything else.
+ * It is recommended to expose all relevant pointers through
+ * retro_get_memory_* as well.
+ *
+ * Can be called from retro_init and retro_load_game.
+ */
+#define RETRO_ENVIRONMENT_SET_GEOMETRY 37
+ /* const struct retro_game_geometry * --
+ * This environment call is similar to SET_SYSTEM_AV_INFO for changing
+ * video parameters, but provides a guarantee that drivers will not be
+ * reinitialized.
+ * This can only be called from within retro_run().
+ *
+ * The purpose of this call is to allow a core to alter nominal
+ * width/heights as well as aspect ratios on-the-fly, which can be
+ * useful for some emulators to change in run-time.
+ *
+ * max_width/max_height arguments are ignored and cannot be changed
+ * with this call as this could potentially require a reinitialization or a
+ * non-constant time operation.
+ * If max_width/max_height are to be changed, SET_SYSTEM_AV_INFO is required.
+ *
+ * A frontend must guarantee that this environment call completes in
+ * constant time.
+ */
+#define RETRO_ENVIRONMENT_GET_USERNAME 38
+ /* const char **
+ * Returns the specified username of the frontend, if specified by the user.
+ * This username can be used as a nickname for a core that has online facilities
+ * or any other mode where personalization of the user is desirable.
+ * The returned value can be NULL.
+ * If this environ callback is used by a core that requires a valid username,
+ * a default username should be specified by the core.
+ */
+#define RETRO_ENVIRONMENT_GET_LANGUAGE 39
+ /* unsigned * --
+ * Returns the specified language of the frontend, if specified by the user.
+ * It can be used by the core for localization purposes.
+ */
+
+#define RETRO_MEMDESC_CONST (1 << 0) /* The frontend will never change this memory area once retro_load_game has returned. */
+#define RETRO_MEMDESC_BIGENDIAN (1 << 1) /* The memory area contains big endian data. Default is little endian. */
+#define RETRO_MEMDESC_ALIGN_2 (1 << 16) /* All memory access in this area is aligned to their own size, or 2, whichever is smaller. */
+#define RETRO_MEMDESC_ALIGN_4 (2 << 16)
+#define RETRO_MEMDESC_ALIGN_8 (3 << 16)
+#define RETRO_MEMDESC_MINSIZE_2 (1 << 24) /* All memory in this region is accessed at least 2 bytes at the time. */
+#define RETRO_MEMDESC_MINSIZE_4 (2 << 24)
+#define RETRO_MEMDESC_MINSIZE_8 (3 << 24)
+struct retro_memory_descriptor
+{
+ uint64_t flags;
+
+ /* Pointer to the start of the relevant ROM or RAM chip.
+ * It's strongly recommended to use 'offset' if possible, rather than
+ * doing math on the pointer.
+ *
+ * If the same byte is mapped my multiple descriptors, their descriptors
+ * must have the same pointer.
+ * If 'start' does not point to the first byte in the pointer, put the
+ * difference in 'offset' instead.
+ *
+ * May be NULL if there's nothing usable here (e.g. hardware registers and
+ * open bus). No flags should be set if the pointer is NULL.
+ * It's recommended to minimize the number of descriptors if possible,
+ * but not mandatory. */
+ void *ptr;
+ size_t offset;
+
+ /* This is the location in the emulated address space
+ * where the mapping starts. */
+ size_t start;
+
+ /* Which bits must be same as in 'start' for this mapping to apply.
+ * The first memory descriptor to claim a certain byte is the one
+ * that applies.
+ * A bit which is set in 'start' must also be set in this.
+ * Can be zero, in which case each byte is assumed mapped exactly once.
+ * In this case, 'len' must be a power of two. */
+ size_t select;
+
+ /* If this is nonzero, the set bits are assumed not connected to the
+ * memory chip's address pins. */
+ size_t disconnect;
+
+ /* This one tells the size of the current memory area.
+ * If, after start+disconnect are applied, the address is higher than
+ * this, the highest bit of the address is cleared.
+ *
+ * If the address is still too high, the next highest bit is cleared.
+ * Can be zero, in which case it's assumed to be infinite (as limited
+ * by 'select' and 'disconnect'). */
+ size_t len;
+
+ /* To go from emulated address to physical address, the following
+ * order applies:
+ * Subtract 'start', pick off 'disconnect', apply 'len', add 'offset'.
+ *
+ * The address space name must consist of only a-zA-Z0-9_-,
+ * should be as short as feasible (maximum length is 8 plus the NUL),
+ * and may not be any other address space plus one or more 0-9A-F
+ * at the end.
+ * However, multiple memory descriptors for the same address space is
+ * allowed, and the address space name can be empty. NULL is treated
+ * as empty.
+ *
+ * Address space names are case sensitive, but avoid lowercase if possible.
+ * The same pointer may exist in multiple address spaces.
+ *
+ * Examples:
+ * blank+blank - valid (multiple things may be mapped in the same namespace)
+ * 'Sp'+'Sp' - valid (multiple things may be mapped in the same namespace)
+ * 'A'+'B' - valid (neither is a prefix of each other)
+ * 'S'+blank - valid ('S' is not in 0-9A-F)
+ * 'a'+blank - valid ('a' is not in 0-9A-F)
+ * 'a'+'A' - valid (neither is a prefix of each other)
+ * 'AR'+blank - valid ('R' is not in 0-9A-F)
+ * 'ARB'+blank - valid (the B can't be part of the address either, because
+ * there is no namespace 'AR')
+ * blank+'B' - not valid, because it's ambigous which address space B1234
+ * would refer to.
+ * The length can't be used for that purpose; the frontend may want
+ * to append arbitrary data to an address, without a separator. */
+ const char *addrspace;
+};
+
+/* The frontend may use the largest value of 'start'+'select' in a
+ * certain namespace to infer the size of the address space.
+ *
+ * If the address space is larger than that, a mapping with .ptr=NULL
+ * should be at the end of the array, with .select set to all ones for
+ * as long as the address space is big.
+ *
+ * Sample descriptors (minus .ptr, and RETRO_MEMFLAG_ on the flags):
+ * SNES WRAM:
+ * .start=0x7E0000, .len=0x20000
+ * (Note that this must be mapped before the ROM in most cases; some of the
+ * ROM mappers
+ * try to claim $7E0000, or at least $7E8000.)
+ * SNES SPC700 RAM:
+ * .addrspace="S", .len=0x10000
+ * SNES WRAM mirrors:
+ * .flags=MIRROR, .start=0x000000, .select=0xC0E000, .len=0x2000
+ * .flags=MIRROR, .start=0x800000, .select=0xC0E000, .len=0x2000
+ * SNES WRAM mirrors, alternate equivalent descriptor:
+ * .flags=MIRROR, .select=0x40E000, .disconnect=~0x1FFF
+ * (Various similar constructions can be created by combining parts of
+ * the above two.)
+ * SNES LoROM (512KB, mirrored a couple of times):
+ * .flags=CONST, .start=0x008000, .select=0x408000, .disconnect=0x8000, .len=512*1024
+ * .flags=CONST, .start=0x400000, .select=0x400000, .disconnect=0x8000, .len=512*1024
+ * SNES HiROM (4MB):
+ * .flags=CONST, .start=0x400000, .select=0x400000, .len=4*1024*1024
+ * .flags=CONST, .offset=0x8000, .start=0x008000, .select=0x408000, .len=4*1024*1024
+ * SNES ExHiROM (8MB):
+ * .flags=CONST, .offset=0, .start=0xC00000, .select=0xC00000, .len=4*1024*1024
+ * .flags=CONST, .offset=4*1024*1024, .start=0x400000, .select=0xC00000, .len=4*1024*1024
+ * .flags=CONST, .offset=0x8000, .start=0x808000, .select=0xC08000, .len=4*1024*1024
+ * .flags=CONST, .offset=4*1024*1024+0x8000, .start=0x008000, .select=0xC08000, .len=4*1024*1024
+ * Clarify the size of the address space:
+ * .ptr=NULL, .select=0xFFFFFF
+ * .len can be implied by .select in many of them, but was included for clarity.
+ */
+
+struct retro_memory_map
+{
+ const struct retro_memory_descriptor *descriptors;
+ unsigned num_descriptors;
+};
+
+struct retro_controller_description
+{
+ /* Human-readable description of the controller. Even if using a generic
+ * input device type, this can be set to the particular device type the
+ * core uses. */
+ const char *desc;
+
+ /* Device type passed to retro_set_controller_port_device(). If the device
+ * type is a sub-class of a generic input device type, use the
+ * RETRO_DEVICE_SUBCLASS macro to create an ID.
+ *
+ * E.g. RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_JOYPAD, 1). */
+ unsigned id;
+};
+
+struct retro_controller_info
+{
+ const struct retro_controller_description *types;
+ unsigned num_types;
+};
+
+struct retro_subsystem_memory_info
+{
+ /* The extension associated with a memory type, e.g. "psram". */
+ const char *extension;
+
+ /* The memory type for retro_get_memory(). This should be at
+ * least 0x100 to avoid conflict with standardized
+ * libretro memory types. */
+ unsigned type;
+};
+
+struct retro_subsystem_rom_info
+{
+ /* Describes what the content is (SGB BIOS, GB ROM, etc). */
+ const char *desc;
+
+ /* Same definition as retro_get_system_info(). */
+ const char *valid_extensions;
+
+ /* Same definition as retro_get_system_info(). */
+ bool need_fullpath;
+
+ /* Same definition as retro_get_system_info(). */
+ bool block_extract;
+
+ /* This is set if the content is required to load a game.
+ * If this is set to false, a zeroed-out retro_game_info can be passed. */
+ bool required;
+
+ /* Content can have multiple associated persistent
+ * memory types (retro_get_memory()). */
+ const struct retro_subsystem_memory_info *memory;
+ unsigned num_memory;
+};
+
+struct retro_subsystem_info
+{
+ /* Human-readable string of the subsystem type, e.g. "Super GameBoy" */
+ const char *desc;
+
+ /* A computer friendly short string identifier for the subsystem type.
+ * This name must be [a-z].
+ * E.g. if desc is "Super GameBoy", this can be "sgb".
+ * This identifier can be used for command-line interfaces, etc.
+ */
+ const char *ident;
+
+ /* Infos for each content file. The first entry is assumed to be the
+ * "most significant" content for frontend purposes.
+ * E.g. with Super GameBoy, the first content should be the GameBoy ROM,
+ * as it is the most "significant" content to a user.
+ * If a frontend creates new file paths based on the content used
+ * (e.g. savestates), it should use the path for the first ROM to do so. */
+ const struct retro_subsystem_rom_info *roms;
+
+ /* Number of content files associated with a subsystem. */
+ unsigned num_roms;
+
+ /* The type passed to retro_load_game_special(). */
+ unsigned id;
+};
+
+typedef void (*retro_proc_address_t)(void);
+
+/* libretro API extension functions:
+ * (None here so far).
+ *
+ * Get a symbol from a libretro core.
+ * Cores should only return symbols which are actual
+ * extensions to the libretro API.
+ *
+ * Frontends should not use this to obtain symbols to standard
+ * libretro entry points (static linking or dlsym).
+ *
+ * The symbol name must be equal to the function name,
+ * e.g. if void retro_foo(void); exists, the symbol must be called "retro_foo".
+ * The returned function pointer must be cast to the corresponding type.
+ */
+typedef retro_proc_address_t (*retro_get_proc_address_t)(const char *sym);
+
+struct retro_get_proc_address_interface
+{
+ retro_get_proc_address_t get_proc_address;
+};