include/interface/c-interface.h

   1 #ifndef _interface__c_interface__h__included__
   2 #define _interface__c_interface__h__included__
   3
   4 /*
   5
   6 Copyright (c) 2013 Ilari Liusvaara
   7
   8 Permission is hereby granted, free of charge, to any person obtaining a copy
   9 of this software and associated documentation files (the "Software"), to deal
  10 in the Software without restriction, including without limitation the rights
  11 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12 copies of the Software, and to permit persons to whom the Software is
  13 furnished to do so, subject to the following conditions:
  14
  15 The above copyright notice and this permission notice shall be included in
  16 all copies or substantial portions of the Software.
  17
  18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  24 THE SOFTWARE.
  25
  26 */
  27
  28 /**
  29  * Some general information about the interface:
  30  * - The parameter type for LSNES_CORE_FOO is struct lsnes_core_foo*
  31  * - There are also some other enumerations/structures.
  32  * - The only exposed entry point (lsnes_core_entrypoint) has fp type of lsnes_core_func_t.
  33  * - By nature, this interface does not reference any symbols (exception is lsnes_register_builtin_core).
  34  * - Some fields may be conditional on API version.
  35  * - The following functions are required:
  36  *   * LSNES_CORE_ENUMERATE_CORES
  37  *   * LSNES_CORE_GET_CORE_INFO
  38  *   * LSNES_CORE_GET_TYPE_INFO
  39  *   * LSNES_CORE_GET_REGION_INFO
  40  *   * LSNES_CORE_GET_SYSREGION_INFO
  41  *   * LSNES_CORE_GET_AV_STATE
  42  *   * LSNES_CORE_EMULATE
  43  *   * LSNES_CORE_SAVESTATE
  44  *   * LSNES_CORE_LOADSTATE
  45  *   * LSNES_CORE_GET_CONTROLLERCONFIG
  46  *   * LSNES_CORE_LOAD_ROM
  47  * - Scratch buffers from emulator side last for duration of the call.
  48  * - Scratch buffers form core side last until next call.
  49  * - Never free buffer from emulator in core or vice versa.
  50  * - The spaces for Core, Type, Region and Sysregion IDs are distinct.
  51  * - If you only have one region, use ID of 0 for that and GET_REGION/SET_REGION are not needed.
  52  */
  53
  54 #include <stdint.h>
  55 #include <time.h>
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 //API version.
  62 #define LSNES_CORE_API 0
  63
  64 /** Constants. **/
  65 //VMA is read-only.
  66 #define LSNES_CORE_VMA_READONLY 1
  67 //VMA has special semantics (no read/write consistency).
  68 #define LSNES_CORE_VMA_SPECIAL 2
  69 //VMA is volatile (and uninitialized on poweron).
  70 #define LSNES_CORE_VMA_VOLATILE 4
  71
  72 /** Capabilities. **/
  73 //Core supports multiple regions (By supporting LSNES_CORE_GET_REGION/LSNES_CORE_SET_REGION).
  74 #define LSNES_CORE_CAP1_MULTIREGION     0x00000001U
  75 //Core supports poll flags (By supporting LSNES_CORE_GET_PFLAG/LSNES_CORE_SET_PFLAG).
  76 #define LSNES_CORE_CAP1_PFLAG           0x00000002U
  77 //Core supports actions (By supporting LSNES_CORE_GET_ACTION_FLAGS/LSNES_CORE_EXECUTE_ACTION).
  78 #define LSNES_CORE_CAP1_ACTION          0x00000004U
  79 //Core supports bus map (By supporting LSNES_CORE_GET_BUS_MAPPING).
  80 #define LSNES_CORE_CAP1_BUSMAP          0x00000008U
  81 //Core supports SRAM (By supporting LSNES_CORE_ENUMERATE_SRAM/LSNES_CORE_LOAD_SRAM/LSNES_CORE_SAVE_SRAM).
  82 #define LSNES_CORE_CAP1_SRAM            0x00000010U
  83 //Core supports resets (By supporting LSNES_CORE_GET_RESET_ACTION). LSNES_CORE_CAP1_ACTION is required.
  84 #define LSNES_CORE_CAP1_RESET           0x00000020U
  85 //Core supports custom scale computation (By supporting LSNES_CORE_COMPUTE_SCALE).
  86 #define LSNES_CORE_CAP1_SCALE           0x00000040U
  87 //Core supports explicit save points (By supporting LSNES_CORE_RUNTOSAVE).
  88 #define LSNES_CORE_CAP1_RUNTOSAVE       0x00000080U
  89 //Core supports powerons (By supporting LSNES_CORE_POWERON).
  90 #define LSNES_CORE_CAP1_POWERON         0x00000100U
  91 //Core supports cartridge unload (By supporting LSNES_CORE_UNLOAD_CARTRIDGE).
  92 #define LSNES_CORE_CAP1_UNLOAD          0x00000200U
  93 //Core supports debugging (By supporting LSNES_CORE_DEBUG_RESET and LSNES_CORE_SET_DEBUG_FLAGS[breakpoints]).
  94 //LSNES_CORE_CAP1_MEMWATCH is required.
  95 #define LSNES_CORE_CAP1_DEBUG           0x00000400U
  96 //Core supports tracing (By supporting LSNES_CORE_DEBUG_RESET and LSNES_CORE_SET_DEBUG_FLAGS[tracing]).
  97 //LSNES_CORE_CAP1_MEMWATCH is required.
  98 #define LSNES_CORE_CAP1_TRACE           0x00000800U
  99 //Core supports cheating (By supporting LSNES_CORE_DEBUG_RESET and LSNES_CORE_SET_CHEAT).
 100 //LSNES_CORE_CAP1_MEMWATCH is required.
 101 #define LSNES_CORE_CAP1_CHEAT           0x00001000U
 102 //Core supports cover pages (By supporting LSNES_CORE_DRAW_COVER).
 103 #define LSNES_CORE_CAP1_COVER           0x00002000U
 104 //Core supports pre-emulate (By supporting LSNES_CORE_PRE_EMULATE).
 105 #define LSNES_CORE_CAP1_PREEMULATE      0x00004000U
 106 //Core supports registers (By supporting LSNES_CORE_GET_DEVICE_REGS).
 107 #define LSNES_CORE_CAP1_REGISTERS       0x00008000U
 108 //Core supports memory watch (By supporting LSNES_CORE_GET_VMA_LIST).
 109 #define LSNES_CORE_CAP1_MEMWATCH        0x00010000U
 110 //Core supports lightguns (By setting lightgun_height/lightgun_width in LSNES_CORE_GET_AV_STATE).
 111 #define LSNES_CORE_CAP1_LIGHTGUN        0x00020000U
 112 //Reserved capabilities.
 113 #define LSNES_CORE_CAP1_RESERVED18      0x00040000U
 114 #define LSNES_CORE_CAP1_RESERVED19      0x00080000U
 115 #define LSNES_CORE_CAP1_RESERVED20      0x00100000U
 116 #define LSNES_CORE_CAP1_RESERVED21      0x00200000U
 117 #define LSNES_CORE_CAP1_RESERVED22      0x00400000U
 118 #define LSNES_CORE_CAP1_RESERVED23      0x00800000U
 119 #define LSNES_CORE_CAP1_RESERVED24      0x01000000U
 120 #define LSNES_CORE_CAP1_RESERVED25      0x02000000U
 121 #define LSNES_CORE_CAP1_RESERVED26      0x04000000U
 122 #define LSNES_CORE_CAP1_RESERVED27      0x08000000U
 123 #define LSNES_CORE_CAP1_RESERVED28      0x10000000U
 124 #define LSNES_CORE_CAP1_RESERVED29      0x20000000U
 125 #define LSNES_CORE_CAP1_RESERVED30      0x40000000U
 126 #define LSNES_CORE_CAP1_CAPS2           0x80000000U
 127
 128 #define LSNES_END_OF_LIST 0xFFFFFFFFU
 129
 130 //Do action <action> on item <item> with parameters <params>.
 131 //If successful, return 0.
 132 //If supported but unsuccessful, return -1 and fill <error> (will not be released, only needs to be stable to next
 133 //call).
 134 //In dynamic libs, this is looked up as lsnes_core_fn.
 135 typedef int(*lsnes_core_func_t)(unsigned action, unsigned item, void* params, const char** error);
 136
 137 //Pixel format.
 138 enum lsnes_core_pixel_format
 139 {
 140         LSNES_CORE_PIXFMT_RGB15,
 141         LSNES_CORE_PIXFMT_BGR15,
 142         LSNES_CORE_PIXFMT_RGB16,
 143         LSNES_CORE_PIXFMT_BGR16,
 144         LSNES_CORE_PIXFMT_RGB24,
 145         LSNES_CORE_PIXFMT_BGR24,
 146         LSNES_CORE_PIXFMT_RGB32,
 147         LSNES_CORE_PIXFMT_LRGB
 148 };
 149
 150 //Framebuffer.
 151 struct lsnes_core_framebuffer_info
 152 {
 153         //Pixel format of framebuffer.
 154         enum lsnes_core_pixel_format type;
 155         //The physical memory backing the framebuffer.
 156         const char* mem;
 157         //Physical width of framebuffer.
 158         size_t physwidth;
 159         //Physical height of framebuffer.
 160         size_t physheight;
 161         //Physical stride of framebuffer (in bytes).
 162         size_t physstride;
 163         //Visible width of framebuffer.
 164         size_t width;
 165         //Visible height of framebuffer.
 166         size_t height;
 167         //Visible stride of framebuffer (in bytes).
 168         size_t stride;
 169         //Visible X offset of framebuffer.
 170         size_t offset_x;
 171         //Visible Y offset of framebuffer.
 172         size_t offset_y;
 173 };
 174
 175 struct lsnes_core_sram
 176 {
 177         //Name.
 178         const char* name;
 179         //Content size.
 180         size_t size;
 181         //Data.
 182         const char* data;
 183 };
 184
 185 struct lsnes_core_system_setting
 186 {
 187         //Name.
 188         const char* name;
 189         //Value.
 190         const char* value;
 191 };
 192
 193 struct lsnes_core_disassembler
 194 {
 195         //Name.
 196         const char* name;
 197         //Routine.
 198         const char* (*fn)(uint64_t base, unsigned char(*fetch)(void* ctx), void* ctx);
 199 };
 200
 201 //Font rendering request.
 202 struct lsnes_core_fontrender_req
 203 {
 204         //Input: Context to pass to callbacks.
 205         void* cb_ctx;
 206         //Input: Allocate bitmap memory.
 207         //cb_ctx => cb_ctx from above.
 208         //mem_size => Number of bytes needed to allocate.
 209         //return buffer at least mem_size bytes. Or return NULL on error.
 210         void* (*alloc)(void* cb_ctx, size_t mem_size);
 211         //Input: Text to render (UTF-8).
 212         const char* text;
 213         //Input: Length of text in bytes. If negative, text is null-terminated.
 214         long text_len;
 215         //Input: Bytes per pixel to request. Can be 1, 2, 3 or 4.
 216         unsigned bytes_pp;
 217         //Input: Foreground color (native endian).
 218         unsigned fg_color;
 219         //Input: Background color (native endian).
 220         unsigned bg_color;
 221         //Output: The allocated bitmap (this comes from ->alloc). Not released on failure.
 222         void* bitmap;
 223         //Output: Width of the bitmap.
 224         size_t width;
 225         //Output: Height of the bitmap.
 226         size_t height;
 227 };
 228
 229 //Request 0: Initialize and enumerate cores.
 230 //Item: 0.
 231 //Default action: (required)
 232 //Called as the first call. Do the needed initialization and return list of core IDs.
 233 #define LSNES_CORE_ENUMERATE_CORES 0
 234 struct lsnes_core_enumerate_cores
 235 {
 236         //Output: List of sysregion ids. Terminated by 0xFFFFFFFF.
 237         unsigned* sysregions;
 238         //Input: Emulator capability flags 1.
 239         unsigned emu_flags1;
 240         //Input: Function to print message line.
 241         void (*message)(const char* msg, size_t length);
 242         //Input: Get input.
 243         short (*get_input)(unsigned port, unsigned index, unsigned control);
 244         //Input: Notify that state of action has updated.
 245         void (*notify_action_update)();
 246         //Input: Notify that time has ticked.
 247         void (*timer_tick)(uint32_t increment, uint32_t per_second);
 248         //Input: Get firmware path. The return value is temporary.
 249         const char* (*get_firmware_path)();
 250         //Input: Get cartridge base path. The return value is temporary.
 251         const char* (*get_base_path)();
 252         //Input: Get current time.
 253         time_t (*get_time)();
 254         //Input: Get random seed.
 255         time_t (*get_randomseed)();
 256         //Input: Notify that memory has been read.
 257         void (*memory_read)(uint64_t addr, uint64_t value);
 258         //Input: Notify that memory is about to be written.
 259         void (*memory_write)(uint64_t addr, uint64_t value);
 260         //Input: Notify that memory is about to be executed.
 261         void (*memory_execute)(uint64_t addr, uint64_t cpunum);
 262         //Input: Notify memory trace event. Str needs to be valid during call.
 263         void (*memory_trace)(uint64_t proc, const char* str, int insn);
 264         //Input: Submit sound.
 265         void (*submit_sound)(const int16_t* samples, size_t count, int stereo, double rate);
 266         //Input: Notify latch event. Parameters are NULL-terminated and need to be remain during call.
 267         void (*notify_latch)(const char** params);
 268         //Input: Output a frame.
 269         void (*submit_frame)(struct lsnes_core_framebuffer_info* fb, uint32_t fps_n, uint32_t fps_d);
 270         //Input: Add disassembler. Only available if emu_flags1>=1.
 271         void* (*add_disasm)(struct lsnes_core_disassembler* disasm);
 272         //Input: Remove disassembler. Only available if emu_flags1>=1.
 273         void (*remove_disasm)(void* handle);
 274         //Input: Render text into bitmap. Returns 0 on success, -1 on failure. Only available if emu_flags>=2.
 275         int (*render_text)(struct lsnes_core_fontrender_req* req);
 276 };
 277
 278 //Request 1: Request information about core.
 279 //Item id: Core ID.
 280 //Default action: (required)
 281 //Obtain information about core.
 282 #define LSNES_CORE_GET_CORE_INFO 1
 283 struct lsnes_core_get_core_info_aparam
 284 {
 285         //Name of the parameter.
 286         const char* name;
 287         //Model:
 288         //bool: boolean
 289         //int:<val>,<val>: Integer in specified range.
 290         //string[:<regex>]: String with regex.
 291         //enum:<json-array-of-strings>: Enumeration.
 292         //toggle: Not a real parameter, boolean toggle, must be the first.
 293         const char* model;
 294 };
 295 struct lsnes_core_get_core_info_action
 296 {
 297         //Internal id of the action.
 298         int id;
 299         //Internal name of the action.
 300         const char* iname;
 301         //Human-readable Name of the action
 302         const char* hname;
 303         //Array of parameters. Terminated by parameter with NULL name.
 304         struct lsnes_core_get_core_info_aparam* parameters;
 305 };
 306 struct lsnes_core_get_core_info
 307 {
 308         //Output: The JSON text.
 309         const char* json;
 310         //Output: JSON pointer to root of the port array.
 311         const char* root_ptr;
 312         //Output: Short core name.
 313         const char* shortname;
 314         //Output: Full core name.
 315         const char* fullname;
 316         //Output: Capability flags #1 (LSNES_CORE_CAP1_*).
 317         unsigned cap_flags1;
 318         //Output: Array of actions. Terminated by action with NUL iname. Only if LSNES_CORE_CAP1_ACTION is set.
 319         struct lsnes_core_get_core_info_action* actions;
 320         //Output: List of trace CPUs. Terminated by NULL. Only if LSNES_CORE_CAP1_TRACE is set.
 321         const char** trace_cpu_list;
 322 };
 323
 324 //Request 2: Request information about system type.
 325 //Item id: Type ID.
 326 //Default action: (required)
 327 //Obtain information about system type.
 328 #define LSNES_CORE_GET_TYPE_INFO 2
 329 struct lsnes_core_get_type_info_paramval
 330 {
 331         const char* iname;
 332         const char* hname;
 333         signed index;
 334 };
 335 struct lsnes_core_get_type_info_param
 336 {
 337         //Internal name.
 338         const char* iname;
 339         //Human-readable name.
 340         const char* hname;
 341         //Default value.
 342         const char* dflt;
 343         //Enumeration of values (if enumerated, ended by value with NULL iname).
 344         //If values are false and true, this is boolean.
 345         struct lsnes_core_get_type_info_paramval* values;
 346         //Validation regex (only for non-enumerated).
 347         const char* regex;
 348 };
 349 struct lsnes_core_get_type_info_romimage
 350 {
 351         //Internal name.
 352         const char* iname;
 353         //Human-readable name.
 354         const char* hname;
 355         //Mandatory mask (OR of all preset ones must equal OR of all).
 356         unsigned mandatory;
 357         //Pass mode: 0 => Content. 1 => Filename, 2 => Directory.
 358         int pass_mode;
 359         //Optional header size.
 360         unsigned headersize;
 361         //Standard extensions (split by ;).
 362         const char* extensions;
 363 };
 364 struct lsnes_core_get_type_info
 365 {
 366         //Output: ID of core emulating this.
 367         unsigned core;
 368         //Output: internal name.
 369         const char* iname;
 370         //Output: human-readable name.
 371         const char* hname;
 372         //Output: Short System name (e.g. SNES).
 373         const char* sysname;
 374         //Output: BIOS name.
 375         const char* bios;
 376         //Output: List of regions. Terminated by 0xFFFFFFFF.
 377         unsigned* regions;
 378         //Output: List of images. Terminated by image with NULL iname.
 379         struct lsnes_core_get_type_info_romimage* images;
 380         //Output: List of settings. Terminated by setting with NULL iname.
 381         struct lsnes_core_get_type_info_param* settings;
 382 };
 383
 384 //Request 3: Request information about region.
 385 //Item id: Region ID.
 386 //Default action: (required)
 387 //Obtain information about region.
 388 #define LSNES_CORE_GET_REGION_INFO 3
 389 struct lsnes_core_get_region_info
 390 {
 391         //Output: Internal name.
 392         const char* iname;
 393         //Output: Human-readable name.
 394         const char* hname;
 395         //Output: Priority
 396         unsigned priority;
 397         //Output: Multi-region flag.
 398         int multi;
 399         //Output: Fps numerator.
 400         uint32_t fps_n;
 401         //Output: Fps denomerator.
 402         uint32_t fps_d;
 403         //Output: Compatible run regions, ended with 0xFFFFFFFF.
 404         unsigned* compatible_runs;
 405 };
 406
 407 //Request 4: Get sysregion info.
 408 //Item id: Sysregion ID.
 409 //Default action: (required)
 410 //Get information about specific sysregion.
 411 #define LSNES_CORE_GET_SYSREGION_INFO 4
 412 struct lsnes_core_get_sysregion_info
 413 {
 414         //Output: The name of sysregion.
 415         const char* name;
 416         //Output: The type ID.
 417         unsigned type;
 418         //Output: The region ID.
 419         unsigned region;
 420         //Output: The system name this is for.
 421         const char* for_system;
 422 };
 423
 424
 425 //Request 5: Get current A/V state.
 426 //Item: Core ID.
 427 //Default action: (required)
 428 //Fill the structure with current A/V state.
 429 #define LSNES_CORE_GET_AV_STATE 5
 430 struct lsnes_core_get_av_state
 431 {
 432         uint32_t fps_n;
 433         uint32_t fps_d;
 434         double par;
 435         uint32_t rate_n;
 436         uint32_t rate_d;
 437         unsigned lightgun_width;
 438         unsigned lightgun_height;
 439 };
 440
 441
 442 //Request 6: Emulate a frame
 443 //Item: Core ID.
 444 //Default action: (required).
 445 //Emulate a frame and output the video and audio data resulting.
 446 #define LSNES_CORE_EMULATE 6
 447 struct lsnes_core_emulate
 448 {
 449 };
 450
 451 //Request 7: Save state.
 452 //Item: Core ID.
 453 //Default action: (required).
 454 //Save core state.
 455 #define LSNES_CORE_SAVESTATE 7
 456 struct lsnes_core_savestate
 457 {
 458         //Output: Size of the savestate.
 459         size_t size;
 460         //Output: Savestate data. Only needs to be stable to next call.
 461         const char* data;
 462 };
 463
 464 //Request 8: Load state.
 465 //Item: Core ID.
 466 //Default action: (required).
 467 //Load core state.
 468 #define LSNES_CORE_LOADSTATE 8
 469 struct lsnes_core_loadstate
 470 {
 471         //Input: Size of the savestate.
 472         size_t size;
 473         //Input: Savestate data. Only stable during call.
 474         const char* data;
 475 };
 476
 477 //Request 9: Get controller set.
 478 //Item id: Type ID.
 479 //Default action: (required).
 480 //Get the controller set.
 481 #define LSNES_CORE_GET_CONTROLLERCONFIG 9
 482 struct lsnes_core_get_controllerconfig_logical_entry
 483 {
 484         //port
 485         unsigned port;
 486         //controller
 487         unsigned controller;
 488 };
 489 struct lsnes_core_get_controllerconfig
 490 {
 491         //Input: System settings. Ended by entry with NULL name.
 492         struct lsnes_core_system_setting* settings;
 493         //Output: Port types, indexed by 0-based ID to port type root JSON array. Ended by 0xFFFFFFFF.
 494         unsigned* controller_types;
 495         //Output: Logical map (ended by 0,0).
 496         struct lsnes_core_get_controllerconfig_logical_entry* logical_map;
 497 };
 498
 499 //Request 10: Load ROM.
 500 //Item id: Type ID.
 501 //Default action: (required).
 502 //Load given ROM.
 503 #define LSNES_CORE_LOAD_ROM 10
 504 struct lsnes_core_load_rom_image
 505 {
 506         //ROM image (or filename thereof)
 507         const char* data;
 508         //Size of ROM image.
 509         size_t size;
 510         //Markup.
 511         const char* markup;
 512 };
 513 struct lsnes_core_load_rom
 514 {
 515         //Input: The image set.
 516         struct lsnes_core_load_rom_image* images;
 517         //Input: System settings. Ended by entry with NULL name.
 518         struct lsnes_core_system_setting* settings;
 519         //Input: RTC second.
 520         uint64_t rtc_sec;
 521         //Input: RTC subsecond.
 522         uint64_t rtc_subsec;
 523 };
 524
 525 //Request 11: Get region.
 526 //Item: Core ID.
 527 //Default action: Fill region 0.
 528 //Return the current region.
 529 #define LSNES_CORE_GET_REGION 11
 530 struct lsnes_core_get_region
 531 {
 532         //Output: The region.
 533         unsigned region;
 534 };
 535
 536 //Request 12: Set region.
 537 //Item: Core ID.
 538 //Default action: If region is 0, succeed, otherwise fail.
 539 //Set current region.
 540 #define LSNES_CORE_SET_REGION 12
 541 struct lsnes_core_set_region
 542 {
 543         //Input: The region ID.
 544         unsigned region;
 545 };
 546
 547 //Request 13: Deinitialize
 548 //Item: 0.
 549 //Default action: No-op
 550 //Deinitialize the state.
 551 #define LSNES_CORE_DEINITIALIZE 13
 552 struct lsnes_core_deinitialize
 553 {
 554 };
 555
 556 //Request 14: Get poll flag state.
 557 //Item: Core ID.
 558 //Default action: Return flag inferred from polls.
 559 //Return the poll flag state.
 560 //The poll flag gets automatically set to 1 if core reads controllers.
 561 #define LSNES_CORE_GET_PFLAG 14
 562 struct lsnes_core_get_pflag
 563 {
 564         //Output: The poll flag state.
 565         int pflag;
 566 };
 567
 568 //Request 15: Set poll flag state.
 569 //Item: Core ID.
 570 //Default action: Set flag inferred from polls.
 571 //Sets the poll flag state.
 572 #define LSNES_CORE_SET_PFLAG 15
 573 struct lsnes_core_set_pflag
 574 {
 575         //Input: The poll flag state.
 576         int pflag;
 577 };
 578
 579 //Request 16: Get action flags.
 580 //Item: Core ID.
 581 //Default action: Act as if flags was 1.
 582 //Get flags for given action.
 583 #define LSNES_CORE_GET_ACTION_FLAGS 16
 584 struct lsnes_core_get_action_flags
 585 {
 586         //Input: The ID of action.
 587         unsigned action;
 588         //Output: The flags.
 589         //Bit 0: Enabled.
 590         //Bit 1: Checked.
 591         unsigned flags;
 592 };
 593
 594 //Request 17: Execute action.
 595 //Item: Core ID.
 596 //Default action: Do nothing.
 597 //Execute given action.
 598 #define LSNES_CORE_EXECUTE_ACTION 17
 599 struct lsnes_core_execute_action_param
 600 {
 601         union {
 602                 int boolean;
 603                 int64_t integer;
 604                 struct {
 605                         const char* base;
 606                         size_t length;
 607                 } string;
 608         };
 609 };
 610 struct lsnes_core_execute_action
 611 {
 612         //Input: The ID of action.
 613         unsigned action;
 614         //Parameters block (length is set by action info).
 615         struct lsnes_core_execute_action_param* params;
 616 };
 617
 618 //Request 18: Get bus mapping.
 619 //Item: Core ID.
 620 //Default action: base=0, size=0 (no mapping).
 621 //Get the base and size of bus mapping.
 622 #define LSNES_CORE_GET_BUS_MAPPING 18
 623 struct lsnes_core_get_bus_mapping
 624 {
 625         //Output: The base address of the mapping.
 626         uint64_t base;
 627         //Output: The size of the mapping.
 628         uint64_t size;
 629 };
 630
 631 //Request 19: Enumerate SRAMs.
 632 //Item iD: Core ID.
 633 //Default action: Return empty set.
 634 //Get the set of SRAMs available.
 635 #define LSNES_CORE_ENUMERATE_SRAM 19
 636 struct lsnes_core_enumerate_sram
 637 {
 638         //Output: List of SRAMs, NULL terminated (valid until next call).
 639         const char** srams;
 640 };
 641
 642 //Request 20: Save SRAMs.
 643 //Item id: Core ID.
 644 //Default action: Return empty set.
 645 //Save the contents of SRAMs.
 646 #define LSNES_CORE_SAVE_SRAM 20
 647 struct lsnes_core_save_sram
 648 {
 649         //Output: The SRAMs, terminated by entry with NULL name. Valid until next call.
 650         struct lsnes_core_sram* srams;
 651 };
 652
 653 //Request 21: Load SRAMs.
 654 //Item id: Core ID.
 655 //Default action: Warn about any SRAMs present.
 656 //Load the contents of SRAMs.
 657 #define LSNES_CORE_LOAD_SRAM 21
 658 struct lsnes_core_load_sram
 659 {
 660         //Intput: The SRAMs, terminated by entry with NULL name. Valid during call.
 661         struct lsnes_core_sram* srams;
 662 };
 663
 664 //Request 22: Get reset action number.
 665 //Item id: Core ID.
 666 //Default action: Return -1 for both (not supported).
 667 //Return the IDs for reset actions.
 668 #define LSNES_CORE_GET_RESET_ACTION 22
 669 struct lsnes_core_get_reset_action
 670 {
 671         //Output: Soft reset action (-1 if not supported).
 672         int softreset;
 673         //Output: Hard reset action (-1 if not supported).
 674         int hardreset;
 675 };
 676
 677 //Request 23: Get scale factors.
 678 //Item id: Core ID.
 679 //Default action: Scale to at least 360 width, 320 height.
 680 //Compute scale factors for given resolution.
 681 #define LSNES_CORE_COMPUTE_SCALE 23
 682 struct lsnes_core_compute_scale
 683 {
 684         //Input: Width
 685         unsigned width;
 686         //Input: Height.
 687         unsigned height;
 688         //Output: Horizontal scale factor.
 689         uint32_t hfactor;
 690         //Output: Vertical scale factor.
 691         uint32_t vfactor;
 692 };
 693
 694 //Request 24: Run to save.
 695 //Item id: Core ID.
 696 //Default action: Do nothing.
 697 //Run to next save point (can be at most frame).
 698 #define LSNES_CORE_RUNTOSAVE 24
 699 struct lsnes_core_runtosave
 700 {
 701 };
 702
 703 //Request 25: Poweron the system
 704 //Item id: Core ID.
 705 //Default action: Do nothing.
 706 //Powers on the emulate system.
 707 #define LSNES_CORE_POWERON 25
 708 struct lsnes_core_poweron
 709 {
 710 };
 711
 712 //Request 26: Unload the ROM.
 713 //Item id: Core ID.
 714 //Default action: Do nothing.
 715 //Signals that the ROM is no longer needed and can be unloaded.
 716 #define LSNES_CORE_UNLOAD_CARTRIDGE 26
 717 struct lsnes_core_unload_cartridge
 718 {
 719 };
 720
 721 //Request 27: Reset debugging.
 722 //Item id: Core ID.
 723 //Default action: Do nothing.
 724 //Signals that debugging system should discard all breakpoints, cheats and tracks.
 725 #define LSNES_CORE_DEBUG_RESET 27
 726 struct lsnes_core_debug_reset
 727 {
 728 };
 729
 730 //Request 28: Set debug flags.
 731 //Item id: Core ID.
 732 //Default action: Do nothing.
 733 //Set debugging flags.
 734 #define LSNES_CORE_SET_DEBUG_FLAGS 28
 735 struct lsnes_core_set_debug_flags
 736 {
 737         //Input: Address or CPU id.
 738         uint64_t addr;
 739         //Input: Flags to set.
 740         //1 => Break on read.
 741         //2 => Break on write.
 742         //4 => Break on execute.
 743         //8 => Trace.
 744         unsigned set;
 745         //Input: Flags to clear.
 746         unsigned clear;
 747 };
 748
 749 //Request 29: Set cheat.
 750 //Item id: Core ID.
 751 //Default action: Do nothing.
 752 //Set or clear cheat.
 753 #define LSNES_CORE_SET_CHEAT 29
 754 struct lsnes_core_set_cheat
 755 {
 756         //Input: Address to set on.
 757         uint64_t addr;
 758         //Input: Value to set.
 759         uint64_t value;
 760         //Input: If nonzero, set cheat, else clear it.
 761         int set;
 762 };
 763
 764 //Request 30: Draw cover page.
 765 //Item id: Core ID.
 766 //Default action: Draw black screen.
 767 //Draw the cover page.
 768 #define LSNES_CORE_DRAW_COVER 30
 769 struct lsnes_core_draw_cover
 770 {
 771         //Output: The cover page. Needs to stay valid to next call.
 772         struct lsnes_core_framebuffer_info* coverpage;
 773 };
 774
 775 //Request 31: Set system controls before emulating frame.
 776 //Item id: Core ID.
 777 //Default action: Do nothing.
 778 //Set the system controls before frame is emulated.
 779 #define LSNES_CORE_PRE_EMULATE 31
 780 struct lsnes_core_pre_emulate
 781 {
 782         //Input: Context to pass to the function.
 783         void* context;
 784         //Input: Set input function.
 785         void (*set_input)(void* context, unsigned port, unsigned controller, unsigned index, short value);
 786 };
 787
 788 //Request 32: Get list of device registers.
 789 //Item id: Core ID.
 790 //Default action: Return no registers.
 791 //Return list of device registers.
 792 #define LSNES_CORE_GET_DEVICE_REGS 32
 793 struct lsnes_core_get_device_regs_reg
 794 {
 795         //Name of the register.
 796         const char* name;
 797         //Read function.
 798         uint64_t (*read)();
 799         //Write function.
 800         void (*write)(uint64_t v);
 801         //Is boolean?
 802         int boolean;
 803 };
 804 struct lsnes_core_get_device_regs
 805 {
 806         //Output: List of registers. Terminated with register with NULL name.
 807         struct lsnes_core_get_device_regs_reg* regs;
 808 };
 809
 810 //Request 33: Get VMA list.
 811 //Item id: Core ID.
 812 //Default action: Return no VMAs.
 813 //Get the list of VMAs.
 814 #define LSNES_CORE_GET_VMA_LIST 33
 815 struct lsnes_core_get_vma_list_vma
 816 {
 817         //Name of region.
 818         const char* name;
 819         //Base address.
 820         uint64_t base;
 821         //Size of region.
 822         uint64_t size;
 823         //Endianess of region (-1 => little, 0 => host, 1 => big).
 824         int endian;
 825         //flags (LSNES_CORE_VMA_*).
 826         int flags;
 827         //Direct mapping for the region. If not NULL, read/write will not be used, instead all operations directly
 828         //manipulate this buffer (faster). Must be NULL for special regions.
 829         unsigned char* direct_map;
 830         //Function to read region (if direct_map is NULL).
 831         uint8_t (*read)(uint64_t offset);
 832         //Function to write region (if direct_map is NULL and readonly is 0).
 833         void (*write)(uint64_t offset, uint8_t value);
 834 };
 835 struct lsnes_core_get_vma_list
 836 {
 837         //Output: List of VMAs. NULL-terminated.
 838         struct lsnes_core_get_vma_list_vma** vmas;
 839 };
 840
 841
 842 #ifdef LSNES_BUILD_AS_BUILTIN_CORE
 843 void lsnes_register_builtin_core(lsnes_core_func_t fn);
 844 #else
 845 int lsnes_core_entrypoint(unsigned action, unsigned item, void* params, const char** error);
 846 #endif
 847
 848 #ifdef __cplusplus
 849 }
 850 #endif
 851
 852 #endif