nanocoat/include/sjme/rom.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * ROM related structures, this replicates what is in @c JarPackageShelf.
  12  *
  13  * @since 2023/12/12
  14  */
  15
  16 #ifndef SQUIRRELJME_ROM_H
  17 #define SQUIRRELJME_ROM_H
  18
  19 #include "sjme/list.h"
  20 #include "sjme/nvm.h"
  21 #include "sjme/romInternal.h"
  22 #include "sjme/stream.h"
  23 #include "sjme/seekable.h"
  24
  25 /* Anti-C++. */
  26 #ifdef __cplusplus
  27         #ifndef SJME_CXX_IS_EXTERNED
  28                 #define SJME_CXX_IS_EXTERNED
  29                 #define SJME_CXX_SQUIRRELJME_ROM_H
  30 extern "C" {
  31         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  32 #endif     /* #ifdef __cplusplus */
  33
  34 /*--------------------------------------------------------------------------*/
  35
  36 /**
  37  * Standard ROM library structure.
  38  *
  39  * @since 2023/12/12
  40  */
  41 typedef struct sjme_rom_libraryCore sjme_rom_libraryCore;
  42
  43 /** Synthetic library structure. */
  44 typedef sjme_rom_libraryCore* sjme_rom_library;
  45
  46 /** List of ROM libraries. */
  47 SJME_LIST_DECLARE(sjme_rom_library, 0);
  48
  49 /** The type ID of ROM libraries. */
  50 #define SJME_TYPEOF_BASIC_sjme_rom_library SJME_BASIC_TYPE_ID_OBJECT
  51
  52 /**
  53  * Common cache between suites and libraries.
  54  *
  55  * @since 2023/12/20
  56  */
  57 typedef struct sjme_rom_cache
  58 {
  59         /** The allocation pool to use. */
  60         sjme_alloc_pool* allocPool;
  61
  62         /** Wrapped object, if applicable. */
  63         sjme_frontEnd frontEnd;
  64
  65         /** Non-common cache size. */
  66         sjme_jint uncommonSize;
  67 } sjme_rom_cache;
  68
  69 /**
  70  * Internal cache for ROM libraries.
  71  *
  72  * @since 2023/12/12
  73  */
  74 typedef struct sjme_rom_libraryCache
  75 {
  76         /** Common cache data. */
  77         sjme_rom_cache common;
  78
  79         /** Cached size of the library. */
  80         sjme_jint size;
  81
  82         /** Is raw access checked? */
  83         sjme_jboolean checkedRawAccess : 1;
  84
  85         /** Is raw access valid. */
  86         sjme_jboolean validRawAccess : 1;
  87
  88         /** Uncommon cache generic structure. */
  89         sjme_jlong uncommon[sjme_flexibleArrayCount];
  90 } sjme_rom_libraryCache;
  91
  92 /**
  93  * Determines the size of the library cache.
  94  *
  95  * @param uncommonSize The uncommon cache size.
  96  * @return The library cache size.
  97  * @since 2023/12/29
  98  */
  99 #define SJME_SIZEOF_LIBRARY_CACHE_N(uncommonSize) \
 100     SJME_SIZEOF_UNCOMMON_N(sjme_rom_libraryCache, uncommon, uncommonSize)
 101
 102 /**
 103  * Determines the size of the library cache.
 104  *
 105  * @param uncommonType The uncommon cache type.
 106  * @return The library cache size.
 107  * @since 2023/12/29
 108  */
 109 #define SJME_SIZEOF_LIBRARY_CACHE(uncommonType) \
 110         SJME_SIZEOF_LIBRARY_CACHE_N(sizeof(uncommonType))
 111
 112 /**
 113  * Internal cache for ROM suites.
 114  *
 115  * @since 2023/12/12
 116  */
 117 typedef struct sjme_rom_suiteCache
 118 {
 119         /** Common cache data. */
 120         sjme_rom_cache common;
 121
 122         /** Libraries that exist within the suite. */
 123         sjme_list_sjme_rom_library* libraries;
 124
 125         /** Uncommon cache generic structure. */
 126         sjme_jlong uncommon[sjme_flexibleArrayCount];
 127 } sjme_rom_suiteCache;
 128
 129 /**
 130  * Determines the size of the suite cache.
 131  *
 132  * @param uncommonSize The uncommon type size.
 133  * @return The suite cache size.
 134  * @since 2023/12/29
 135  */
 136 #define SJME_SIZEOF_SUITE_CACHE_N(uncommonSize) \
 137     SJME_SIZEOF_UNCOMMON_N(sjme_rom_suiteCache, uncommon, uncommonSize)
 138
 139 /**
 140  * Determines the size of the suite cache.
 141  *
 142  * @param uncommonType The uncommon cache type.
 143  * @return The suite cache size.
 144  * @since 2023/12/21
 145  */
 146 #define SJME_SIZEOF_SUITE_CACHE(uncommonType) \
 147         SJME_SIZEOF_SUITE_CACHE_N(sizeof(uncommonType))
 148
 149 /**
 150  * Functions used to access a single library.
 151  *
 152  * @since 2023/12/12
 153  */
 154 typedef struct sjme_rom_libraryFunctions sjme_rom_libraryFunctions;
 155
 156 struct sjme_rom_libraryCore
 157 {
 158         /** Functions used to access library information. */
 159         const sjme_rom_libraryFunctions* functions;
 160
 161         /** The library ID. */
 162         sjme_jint id;
 163
 164         /** The library name. */
 165         sjme_lpcstr name;
 166
 167         /** Hash of the library name. */
 168         sjme_jint nameHash;
 169
 170         /** Internal cache, used by internal library functions. */
 171         sjme_rom_libraryCache cache;
 172 };
 173
 174 /**
 175  * Determines the size of the library core.
 176  *
 177  * @param uncommonSize The uncommon cache size.
 178  * @return The library core size.
 179  * @since 2023/12/29
 180  */
 181 #define SJME_SIZEOF_LIBRARY_CORE_N(uncommonSize) \
 182     (sizeof(sjme_rom_libraryCore) + \
 183                 (SJME_SIZEOF_LIBRARY_CACHE_N(uncommonSize) - \
 184                 sizeof(sjme_rom_libraryCache)))
 185
 186 /**
 187  * Determines the size of the library core.
 188  *
 189  * @param uncommonType The uncommon cache type.
 190  * @return The library core size.
 191  * @since 2023/12/29
 192  */
 193 #define SJME_SIZEOF_LIBRARY_CORE(uncommonType) \
 194     SJME_SIZEOF_LIBRARY_CORE_N(sizeof(sjme_rom_libraryCore))
 195
 196 /**
 197  * Functions used to access a suite, which is an entire ROM.
 198  *
 199  * @since 2023/12/12
 200  */
 201 typedef struct sjme_rom_suiteFunctions sjme_rom_suiteFunctions;
 202
 203 /**
 204  * Initializes the library cache.
 205  *
 206  * @param inLibrary The input library.
 207  * @return Any resultant error, if any.
 208  * @since 2023/12/29
 209  */
 210 typedef sjme_errorCode (*sjme_rom_libraryInitCacheFunc)(
 211         sjme_attrInNotNull sjme_rom_library inLibrary);
 212
 213 typedef sjme_errorCode (*sjme_rom_libraryPathFunc)();
 214
 215 /**
 216  * Access the direct raw data of a given library.
 217  *
 218  * @param inLibrary The library to access in a raw fashion.
 219  * @param dest The destination buffer.
 220  * @param srcPos The source position within the file.
 221  * @param length The number of bytes to read.
 222  * @return Any resultant error, if any.
 223  * @since 2023/12/30
 224  */
 225 typedef sjme_errorCode (*sjme_rom_libraryRawData)(
 226         sjme_attrInNotNull sjme_rom_library inLibrary,
 227         sjme_attrOutNotNullBuf(length) sjme_pointer dest,
 228         sjme_attrInPositive sjme_jint srcPos,
 229         sjme_attrInPositive sjme_jint length);
 230
 231 /**
 232  * Returns the raw size of the library, also can be used to check if raw
 233  * access is supported in opaque handlers.
 234  *
 235  * @param inLibrary The input library
 236  * @param outSize The output raw size, if the result is @c -1 then it indicates
 237  * that this operation is not supported on the given library and it should
 238  * not try to access resources and otherwise using raw data access.
 239  * @return Any resultant error code.
 240  * @since 2023/12/30
 241  */
 242 typedef sjme_errorCode (*sjme_rom_libraryRawSizeFunc)(
 243         sjme_attrInNotNull sjme_rom_library inLibrary,
 244         sjme_attrOutNotNull sjme_jint* outSize);
 245
 246 /**
 247  * Opens the given resource as a stream.
 248  *
 249  * @param inLibrary The library to read the resource from.
 250  * @param outStream The resultant stream for accessing data.
 251  * @param resourceName The name of the resource.
 252  * @return Any resultant error code.
 253  * @since 2023/12/30
 254  */
 255 typedef sjme_errorCode (*sjme_rom_libraryResourceStreamFunc)(
 256         sjme_attrInNotNull sjme_rom_library inLibrary,
 257         sjme_attrOutNotNull sjme_stream_input* outStream,
 258         sjme_attrInNotNull sjme_lpcstr resourceName);
 259
 260 /**
 261  * Function used to initialize the suite cache.
 262  *
 263  * @param inSuite The input suite.
 264  * @return Any error state.
 265  * @since 2023/12/15
 266  */
 267 typedef sjme_errorCode (*sjme_rom_suiteInitCacheFunc)(
 268         sjme_attrInNotNull sjme_rom_suite inSuite);
 269
 270 /**
 271  * Returns the ID of the library for the given suite.
 272  *
 273  * @param functions The suite functions.
 274  * @param targetSuite The current suite being accessed.
 275  * @param targetLibrary The library to get the ID of.
 276  * @param outId The output library ID, cannot be zero.
 277  * @return Any resultant error code.
 278  * @since 2023/12/18
 279  */
 280 typedef sjme_errorCode (*sjme_rom_suiteLibraryId)(
 281         sjme_attrInNotNull sjme_rom_suite targetSuite,
 282         sjme_attrInNotNull sjme_rom_library targetLibrary,
 283         sjme_attrOutNotNull sjme_jint* outId);
 284
 285 /**
 286  * Determines the list of libraries within the suite.
 287  *
 288  * @param targetSuite The suite the request is being made in.
 289  * @param outLibraries The output library list.
 290  * @return Any resultant error code.
 291  * @since 2023/12/21
 292  */
 293 typedef sjme_errorCode (*sjme_rom_suiteListLibrariesFunc)(
 294         sjme_attrInNotNull sjme_rom_suite targetSuite,
 295         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibraries);
 296
 297 typedef sjme_errorCode (*sjme_rom_suiteLoadLibraryFunc)();
 298
 299 struct sjme_rom_libraryFunctions
 300 {
 301         /** Size of the cache type. */
 302         sjme_jint uncommonTypeSize;
 303
 304         /** Initializes the library cache. */
 305         sjme_rom_libraryInitCacheFunc initCache;
 306
 307         /** Function to get the path of a library. */
 308         sjme_rom_libraryPathFunc path;
 309
 310         /** Access of raw bytes of the input library. */
 311         sjme_rom_libraryRawData rawData;
 312
 313         /** The size of this library. */
 314         sjme_rom_libraryRawSizeFunc rawSize;
 315
 316         /** Access a resource as a stream. */
 317         sjme_rom_libraryResourceStreamFunc resourceStream;
 318 };
 319
 320 struct sjme_rom_suiteFunctions
 321 {
 322         /** Size of the cache type. */
 323         sjme_jint uncommonTypeSize;
 324
 325         /** Initialize suite cache. */
 326         sjme_rom_suiteInitCacheFunc initCache;
 327
 328         /** Returns the ID of the given library. */
 329         sjme_rom_suiteLibraryId libraryId;
 330
 331         /** Lists the libraries in the suite. */
 332         sjme_rom_suiteListLibrariesFunc list;
 333
 334         /** Loads a single library. */
 335         sjme_rom_suiteLoadLibraryFunc loadLibrary;
 336 };
 337
 338 struct sjme_rom_suiteCore
 339 {
 340         /** Functions. */
 341         const sjme_rom_suiteFunctions* functions;
 342
 343         /** Internal cache, used by suite implementations. */
 344         sjme_rom_suiteCache cache;
 345 };
 346
 347 /**
 348  * Determines the size of the suite core.
 349  *
 350  * @param uncommonSize The uncommon cache size.
 351  * @return The suite core size.
 352  * @since 2023/12/29
 353  */
 354 #define SJME_SIZEOF_SUITE_CORE_N(uncommonSize) \
 355     (sizeof(sjme_rom_suiteCore) + (SJME_SIZEOF_SUITE_CACHE_N(uncommonSize) - \
 356                 sizeof(sjme_rom_suiteCache)))
 357
 358 /**
 359  * Determines the size of the suite core.
 360  *
 361  * @param uncommonType The uncommon cache type.
 362  * @return The suite core size.
 363  * @since 2023/12/29
 364  */
 365 #define SJME_SIZEOF_SUITE_CORE(uncommonType) \
 366     SJME_SIZEOF_SUITE_CORE_N(sizeof(sjme_rom_suiteCache))
 367
 368 /**
 369  * Initializes a library from a Zip.
 370  *
 371  * @param pool The pool to use for allocations.
 372  * @param outLibrary The resultant library.
 373  * @param base The base address where the Zip is.
 374  * @param length The length of the Zip.
 375  * @return Any resultant error, if any.
 376  * @since 2024/01/01
 377  */
 378 sjme_errorCode sjme_rom_libraryFromZipMemory(
 379         sjme_attrInNotNull sjme_alloc_pool* pool,
 380         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 381         sjme_attrInNotNull sjme_cpointer base,
 382         sjme_attrInPositive sjme_jint length);
 383
 384 /**
 385  * Initializes a library from a Zip.
 386  *
 387  * @param pool The pool to use for allocations.
 388  * @param outLibrary The resultant library.
 389  * @param seekable The seekable to access the Zip through.
 390  * @return Any resultant error, if any.
 391  * @since 2024/01/01
 392  */
 393 sjme_errorCode sjme_rom_libraryFromZipSeekable(
 394         sjme_attrInNotNull sjme_alloc_pool* pool,
 395         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 396         sjme_attrInNotNull sjme_seekable seekable);
 397
 398 /**
 399  * Calculates the hash of the given library.
 400  *
 401  * @param library The library to calculate the hash of.
 402  * @param outHash The output hash.
 403  * @return On any resultant error.
 404  * @since 2023/12/27
 405  */
 406 sjme_errorCode sjme_rom_libraryHash(
 407         sjme_attrInNotNull sjme_rom_library library,
 408         sjme_attrOutNotNull sjme_jint* outHash);
 409
 410 /**
 411  * Makes a virtual library from the given functions.
 412  *
 413  * @param pool The pool to allocate within.
 414  * @param outLibrary The output library.
 415  * @param inFunctions The functions which define how to access the library.
 416  * @param inFrontEnd Input front end initialization, is optional.
 417  * @return Any error code.
 418  * @since 2023/12/29
 419  */
 420 sjme_errorCode sjme_rom_libraryNew(
 421         sjme_attrInNotNull sjme_alloc_pool* pool,
 422         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 423         sjme_attrInNotNull const sjme_rom_libraryFunctions* inFunctions,
 424         sjme_attrInNullable const sjme_frontEnd* inFrontEnd);
 425
 426 /**
 427  * Reads from a library directly to access its raw bytes.
 428  *
 429  * @param library The library to access.
 430  * @param destPtr The destination buffer.
 431  * @param srcPos The source position.
 432  * @param length The number of bytes to read.
 433  * @return Any resultant error if any.
 434  * @since 2023/12/30
 435  */
 436 sjme_errorCode sjme_rom_libraryRawRead(
 437         sjme_attrInNotNull sjme_rom_library library,
 438         sjme_attrOutNotNullBuf(length) sjme_pointer destPtr,
 439         sjme_attrInPositive sjme_jint srcPos,
 440         sjme_attrInPositive sjme_jint length);
 441
 442 /**
 443  * Reads from a library directly to access its raw bytes, this variant of
 444  * the function provides more control over offsets so that it can more easily
 445  * be used with iterators and such.
 446  *
 447  * @param library The library to access.
 448  * @param destPtr The destination buffer.
 449  * @param destOffset The offset into the destination.
 450  * @param srcPos The source position.
 451  * @param srcOffset The source offset.
 452  * @param length The number of bytes to read.
 453  * @return Any resultant error if any.
 454  * @since 2023/12/30
 455  */
 456 sjme_errorCode sjme_rom_libraryRawReadIter(
 457         sjme_attrInNotNull sjme_rom_library library,
 458         sjme_attrOutNotNullBuf(length) void* destPtr,
 459         sjme_attrInPositive sjme_jint destOffset,
 460         sjme_attrInPositive sjme_jint srcPos,
 461         sjme_attrInPositive sjme_jint srcOffset,
 462         sjme_attrInPositive sjme_jint length);
 463
 464 /**
 465  * Returns the raw size of the library.
 466  *
 467  * @param library The library to get the raw size of.
 468  * @param outSize The resultant size.
 469  * @return Any resultant error code.
 470  * @since 2023/12/30
 471  */
 472 sjme_errorCode sjme_rom_libraryRawSize(
 473         sjme_attrInNotNull sjme_rom_library library,
 474         sjme_attrOutNotNull sjme_jint* outSize);
 475
 476 /**
 477  * Obtains the given resource as a stream.
 478  *
 479  * @param library The library to get the resource from.
 480  * @param outStream The resultant stream.
 481  * @param rcName The name of the resource to obtain.
 482  * @return On any errors, if any.
 483  * @since 2023/12/31
 484  */
 485 sjme_errorCode sjme_rom_libraryResourceAsStream(
 486         sjme_attrInNotNull sjme_rom_library library,
 487         sjme_attrOutNotNull sjme_stream_input* outStream,
 488         sjme_attrInNotNull sjme_lpcstr rcName);
 489
 490 /**
 491  * Resolves the class path library by their ID.
 492  *
 493  * @param inSuite The suite to look within.
 494  * @param inIds The IDs to obtain.
 495  * @param outLibs The output libraries.
 496  * @return Any resultant error state.
 497  * @since 2023/12/18
 498  */
 499 sjme_errorCode sjme_rom_resolveClassPathById(
 500         sjme_attrInNotNull sjme_rom_suite inSuite,
 501         sjme_attrInNotNull const sjme_list_sjme_jint* inIds,
 502         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 503
 504 /**
 505  * Resolves the class path library by their name.
 506  *
 507  * @param inSuite The suite to look within.
 508  * @param inNames The names to obtain.
 509  * @param outLibs The output libraries.
 510  * @return Any resultant error state.
 511  * @since 2023/12/18
 512  */
 513 sjme_errorCode sjme_rom_resolveClassPathByName(
 514         sjme_attrInNotNull sjme_rom_suite inSuite,
 515         sjme_attrInNotNull const sjme_list_sjme_lpcstr* inNames,
 516         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 517
 518 /**
 519  * Combines multiple suites into one.
 520  *
 521  * @param pool The pool to allocate within.
 522  * @param outSuite The output suite.
 523  * @param inSuites The input suites.
 524  * @param numInSuites The number of input suites.
 525  * @return
 526  */
 527 sjme_errorCode sjme_rom_suiteFromMerge(
 528         sjme_attrInNotNull sjme_alloc_pool* pool,
 529         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 530         sjme_attrInNotNull sjme_rom_suite* inSuites,
 531         sjme_attrInPositive sjme_jint numInSuites);
 532
 533 /**
 534  * Scans the payload for suites
 535  *
 536  * @param pool The pool to allocate within.
 537  * @param outSuite The output resultant suite, if there would be nothing in
 538  * here then this outputs @c NULL .
 539  * @param payloadConfig The payload configuration used.
 540  * @return Any error status.
 541  * @since 2023/12/15
 542  */
 543 sjme_errorCode sjme_rom_suiteFromPayload(
 544         sjme_attrInNotNull sjme_alloc_pool* pool,
 545         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 546         sjme_attrInNotNull const sjme_payload_config* payloadConfig);
 547
 548 /**
 549  * Returns all of the libraries which are available within this suite.
 550  *
 551  * @param inSuite The input suite.
 552  * @param outLibs The resultant libraries.
 553  * @return Any resultant error state.
 554  * @since 2023/12/20
 555  */
 556 sjme_errorCode sjme_rom_suiteLibraries(
 557         sjme_attrInNotNull sjme_rom_suite inSuite,
 558         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 559
 560 /**
 561  * Makes a virtual suite from the given functions.
 562  *
 563  * @param pool The pool to allocate within.
 564  * @param outSuite The output suite.
 565  * @param inFunctions The functions which define how to access the suite.
 566  * @param inFrontEnd Input front end initialization, is optional.
 567  * @return Any error code.
 568  * @since 2023/12/15
 569  */
 570 sjme_errorCode sjme_rom_suiteNew(
 571         sjme_attrInNotNull sjme_alloc_pool* pool,
 572         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 573         sjme_attrInNotNull const sjme_rom_suiteFunctions* inFunctions,
 574         sjme_attrInNullable const sjme_frontEnd* inFrontEnd);
 575
 576 /*--------------------------------------------------------------------------*/
 577
 578 /* Anti-C++. */
 579 #ifdef __cplusplus
 580         #ifdef SJME_CXX_SQUIRRELJME_ROM_H
 581 }
 582                 #undef SJME_CXX_SQUIRRELJME_ROM_H
 583                 #undef SJME_CXX_IS_EXTERNED
 584         #endif /* #ifdef SJME_CXX_SQUIRRELJME_ROM_H */
 585 #endif     /* #ifdef __cplusplus */
 586
 587 #endif /* SQUIRRELJME_ROM_H */