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/nvm.h"
  20 #include "sjme/list.h"
  21 #include "sjme/romInternal.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_ROM_H
  28 extern "C" {
  29         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  30 #endif     /* #ifdef __cplusplus */
  31
  32 /*--------------------------------------------------------------------------*/
  33
  34 /**
  35  * Standard ROM library structure.
  36  *
  37  * @since 2023/12/12
  38  */
  39 typedef struct sjme_rom_libraryCore sjme_rom_libraryCore;
  40
  41 /** Synthetic library structure. */
  42 typedef sjme_rom_libraryCore* sjme_rom_library;
  43
  44 /** List of ROM libraries. */
  45 SJME_LIST_DECLARE(sjme_rom_library, 0);
  46
  47 /** The type ID of ROM libraries. */
  48 #define SJME_BASIC_TYPEOF_sjme_rom_library SJME_BASIC_TYPE_ID_OBJECT
  49
  50 /**
  51  * Common cache between suites and libraries.
  52  *
  53  * @since 2023/12/20
  54  */
  55 typedef struct sjme_rom_cache
  56 {
  57         /** The allocation pool to use. */
  58         sjme_alloc_pool* allocPool;
  59
  60         /** Wrapped object, if applicable. */
  61         sjme_frontEnd frontEnd;
  62
  63         /** Non-common cache size. */
  64         sjme_jint uncommonSize;
  65 } sjme_rom_cache;
  66
  67 /**
  68  * Internal cache for ROM libraries.
  69  *
  70  * @since 2023/12/12
  71  */
  72 typedef struct sjme_rom_libraryCache
  73 {
  74         /** Common cache data. */
  75         sjme_rom_cache common;
  76
  77         /** Uncommon cache generic structure. */
  78         sjme_jubyte uncommon[sjme_flexibleArrayCount];
  79 } sjme_rom_libraryCache;
  80
  81 /**
  82  * Determines the size of the library cache.
  83  *
  84  * @param uncommonSize The uncommon cache size.
  85  * @return The library cache size.
  86  * @since 2023/12/29
  87  */
  88 #define SJME_SIZEOF_LIBRARY_CACHE_N(uncommonSize) \
  89         (sizeof(sjme_rom_libraryCache) + (offsetof(sjme_rom_libraryCache, \
  90                 uncommon[0]) - offsetof(sjme_rom_libraryCache, uncommon)) + \
  91                 (uncommonSize))
  92
  93 /**
  94  * Determines the size of the library cache.
  95  *
  96  * @param uncommonType The uncommon cache type.
  97  * @return The library cache size.
  98  * @since 2023/12/29
  99  */
 100 #define SJME_SIZEOF_LIBRARY_CACHE(uncommonType) \
 101         SJME_SIZEOF_LIBRARY_CACHE_N(sizeof(uncommonType))
 102
 103 /**
 104  * Internal cache for ROM suites.
 105  *
 106  * @since 2023/12/12
 107  */
 108 typedef struct sjme_rom_suiteCache
 109 {
 110         /** Common cache data. */
 111         sjme_rom_cache common;
 112
 113         /** Libraries that exist within the suite. */
 114         sjme_list_sjme_rom_library* libraries;
 115
 116         /** Uncommon cache generic structure. */
 117         sjme_jlong uncommon[sjme_flexibleArrayCount];
 118 } sjme_rom_suiteCache;
 119
 120 /**
 121  * Determines the size of the suite cache.
 122  *
 123  * @param uncommonSize The uncommon type size.
 124  * @return The suite cache size.
 125  * @since 2023/12/29
 126  */
 127 #define SJME_SIZEOF_SUITE_CACHE_N(uncommonSize) \
 128         (sizeof(sjme_rom_suiteCache) + (offsetof(sjme_rom_suiteCache, \
 129                 uncommon[0]) - offsetof(sjme_rom_suiteCache, uncommon)) + \
 130                 (uncommonSize))
 131
 132 /**
 133  * Determines the size of the suite cache.
 134  *
 135  * @param uncommonType The uncommon cache type.
 136  * @return The suite cache size.
 137  * @since 2023/12/21
 138  */
 139 #define SJME_SIZEOF_SUITE_CACHE(uncommonType) \
 140         SJME_SIZEOF_SUITE_CACHE_N(sizeof(uncommonType))
 141
 142 /**
 143  * Functions used to access a single library.
 144  *
 145  * @since 2023/12/12
 146  */
 147 typedef struct sjme_rom_libraryFunctions sjme_rom_libraryFunctions;
 148
 149 struct sjme_rom_libraryCore
 150 {
 151         /** Functions used to access library information. */
 152         const sjme_rom_libraryFunctions* functions;
 153
 154         /** The library ID. */
 155         sjme_jint id;
 156
 157         /** The library name. */
 158         sjme_lpcstr name;
 159
 160         /** Hash of the library name. */
 161         sjme_jint nameHash;
 162
 163         /** Internal cache, used by internal library functions. */
 164         sjme_rom_libraryCache cache;
 165 };
 166
 167 /**
 168  * Determines the size of the library core.
 169  *
 170  * @param uncommonSize The uncommon cache size.
 171  * @return The library core size.
 172  * @since 2023/12/29
 173  */
 174 #define SJME_SIZEOF_LIBRARY_CORE_N(uncommonSize) \
 175     (sizeof(sjme_rom_libraryCore) + \
 176                 (SJME_SIZEOF_LIBRARY_CACHE_N(uncommonSize) - \
 177                 sizeof(sjme_rom_libraryCache)))
 178
 179 /**
 180  * Determines the size of the library core.
 181  *
 182  * @param uncommonType The uncommon cache type.
 183  * @return The library core size.
 184  * @since 2023/12/29
 185  */
 186 #define SJME_SIZEOF_LIBRARY_CORE(uncommonType) \
 187     SJME_SIZEOF_LIBRARY_CORE_N(sizeof(sjme_rom_libraryCore))
 188
 189 /**
 190  * Functions used to access a suite, which is an entire ROM.
 191  *
 192  * @since 2023/12/12
 193  */
 194 typedef struct sjme_rom_suiteFunctions sjme_rom_suiteFunctions;
 195
 196 /**
 197  * Initializes the library cache.
 198  *
 199  * @param inLibrary The input library.
 200  * @return Any resultant error, if any.
 201  * @since 2023/12/29
 202  */
 203 typedef sjme_errorCode (*sjme_rom_libraryInitCacheFunc)(
 204         sjme_attrInNotNull sjme_rom_library inLibrary);
 205
 206 typedef sjme_errorCode (*sjme_rom_libraryPathFunc)();
 207
 208 typedef sjme_errorCode (*sjme_rom_libraryResourceDirectFunc)();
 209
 210 typedef sjme_errorCode (*sjme_rom_libraryResourceStreamFunc)();
 211
 212 typedef sjme_errorCode (*sjme_rom_libraryRawData)();
 213
 214 typedef sjme_errorCode (*sjme_rom_librarySizeFunc)();
 215
 216 /**
 217  * Function used to initialize the suite cache.
 218  *
 219  * @param inSuite The input suite.
 220  * @return Any error state.
 221  * @since 2023/12/15
 222  */
 223 typedef sjme_errorCode (*sjme_rom_suiteInitCacheFunc)(
 224         sjme_attrInNotNull sjme_rom_suite inSuite);
 225
 226 /**
 227  * Returns the ID of the library for the given suite.
 228  *
 229  * @param functions The suite functions.
 230  * @param targetSuite The current suite being accessed.
 231  * @param targetLibrary The library to get the ID of.
 232  * @param outId The output library ID, cannot be zero.
 233  * @return Any resultant error code.
 234  * @since 2023/12/18
 235  */
 236 typedef sjme_errorCode (*sjme_rom_suiteLibraryId)(
 237         sjme_attrInNotNull sjme_rom_suite targetSuite,
 238         sjme_attrInNotNull sjme_rom_library targetLibrary,
 239         sjme_attrOutNotNull sjme_jint* outId);
 240
 241 /**
 242  * Determines the list of libraries within the suite.
 243  *
 244  * @param targetSuite The suite the request is being made in.
 245  * @param outLibraries The output library list.
 246  * @return Any resultant error code.
 247  * @since 2023/12/21
 248  */
 249 typedef sjme_errorCode (*sjme_rom_suiteListLibrariesFunc)(
 250         sjme_attrInNotNull sjme_rom_suite targetSuite,
 251         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibraries);
 252
 253 typedef sjme_errorCode (*sjme_rom_suiteLoadLibraryFunc)();
 254
 255 struct sjme_rom_libraryFunctions
 256 {
 257         /** Size of the cache type. */
 258         sjme_jint uncommonTypeSize;
 259
 260         /** Initializes the library cache. */
 261         sjme_rom_libraryInitCacheFunc initCache;
 262
 263         /** Function to get the path of a library. */
 264         sjme_rom_libraryPathFunc path;
 265
 266         /** Direct resource access, if available. */
 267         sjme_rom_libraryResourceDirectFunc resourceDirect;
 268
 269         /** Open resource as a stream. */
 270         sjme_rom_libraryResourceStreamFunc resourceStream;
 271
 272         /** Access of raw bytes of the input library. */
 273         sjme_rom_libraryRawData rawData;
 274
 275         /** The size of this library. */
 276         sjme_rom_librarySizeFunc size;
 277 };
 278
 279 struct sjme_rom_suiteFunctions
 280 {
 281         /** Size of the cache type. */
 282         sjme_jint uncommonTypeSize;
 283
 284         /** Initialize suite cache. */
 285         sjme_rom_suiteInitCacheFunc initCache;
 286
 287         /** Returns the ID of the given library. */
 288         sjme_rom_suiteLibraryId libraryId;
 289
 290         /** Lists the libraries in the suite. */
 291         sjme_rom_suiteListLibrariesFunc list;
 292
 293         /** Loads a single library. */
 294         sjme_rom_suiteLoadLibraryFunc loadLibrary;
 295 };
 296
 297 struct sjme_rom_suiteCore
 298 {
 299         /** Functions. */
 300         const sjme_rom_suiteFunctions* functions;
 301
 302         /** Internal cache, used by suite implementations. */
 303         sjme_rom_suiteCache cache;
 304 };
 305
 306 /**
 307  * Determines the size of the suite core.
 308  *
 309  * @param uncommonSize The uncommon cache size.
 310  * @return The suite core size.
 311  * @since 2023/12/29
 312  */
 313 #define SJME_SIZEOF_SUITE_CORE_N(uncommonSize) \
 314     (sizeof(sjme_rom_suiteCore) + (SJME_SIZEOF_SUITE_CACHE_N(uncommonSize) - \
 315                 sizeof(sjme_rom_suiteCache)))
 316
 317 /**
 318  * Determines the size of the suite core.
 319  *
 320  * @param uncommonType The uncommon cache type.
 321  * @return The suite core size.
 322  * @since 2023/12/29
 323  */
 324 #define SJME_SIZEOF_SUITE_CORE(uncommonType) \
 325     SJME_SIZEOF_SUITE_CORE_N(sizeof(sjme_rom_suiteCache))
 326
 327 /**
 328  * Combines multiple suites into one.
 329  *
 330  * @param pool The pool to allocate within.
 331  * @param outSuite The output suite.
 332  * @param inSuites The input suites.
 333  * @param numInSuites The number of input suites.
 334  * @return
 335  */
 336 sjme_errorCode sjme_rom_fromMerge(
 337         sjme_attrInNotNull sjme_alloc_pool* pool,
 338         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 339         sjme_attrInNotNull sjme_rom_suite* inSuites,
 340         sjme_attrInPositive sjme_jint numInSuites);
 341
 342 /**
 343  * Scans the payload for suites
 344  *
 345  * @param pool The pool to allocate within.
 346  * @param outSuite The output resultant suite, if there would be nothing in
 347  * here then this outputs @c NULL .
 348  * @param payloadConfig The payload configuration used.
 349  * @return Any error status.
 350  * @since 2023/12/15
 351  */
 352 sjme_errorCode sjme_rom_fromPayload(
 353         sjme_attrInNotNull sjme_alloc_pool* pool,
 354         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 355         sjme_attrInNotNull const sjme_payload_config* payloadConfig);
 356
 357 /**
 358  * Calculates the hash of the given library.
 359  *
 360  * @param library The library to calculate the hash of.
 361  * @param outHash The output hash.
 362  * @return On any resultant error.
 363  * @since 2023/12/27
 364  */
 365 sjme_errorCode sjme_rom_libraryHash(
 366         sjme_attrInNotNull sjme_rom_library library,
 367         sjme_attrOutNotNull sjme_jint* outHash);
 368
 369 /**
 370  * Makes a virtual library from the given functions.
 371  *
 372  * @param pool The pool to allocate within.
 373  * @param outLibrary The output library.
 374  * @param inFunctions The functions which define how to access the library.
 375  * @param inFrontEnd Input front end initialization, is optional.
 376  * @return Any error code.
 377  * @since 2023/12/29
 378  */
 379 sjme_errorCode sjme_rom_newLibrary(
 380         sjme_attrInNotNull sjme_alloc_pool* pool,
 381         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 382         sjme_attrInNotNull const sjme_rom_libraryFunctions* inFunctions,
 383         sjme_attrInNullable const sjme_frontEnd* inFrontEnd);
 384
 385 /**
 386  * Makes a virtual suite from the given functions.
 387  *
 388  * @param pool The pool to allocate within.
 389  * @param outSuite The output suite.
 390  * @param inFunctions The functions which define how to access the suite.
 391  * @param inFrontEnd Input front end initialization, is optional.
 392  * @return Any error code.
 393  * @since 2023/12/15
 394  */
 395 sjme_errorCode sjme_rom_newSuite(
 396         sjme_attrInNotNull sjme_alloc_pool* pool,
 397         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 398         sjme_attrInNotNull const sjme_rom_suiteFunctions* inFunctions,
 399         sjme_attrInNullable const sjme_frontEnd* inFrontEnd);
 400
 401 /**
 402  * Resolves the class path library by their ID.
 403  *
 404  * @param inSuite The suite to look within.
 405  * @param inIds The IDs to obtain.
 406  * @param outLibs The output libraries.
 407  * @return Any resultant error state.
 408  * @since 2023/12/18
 409  */
 410 sjme_errorCode sjme_rom_resolveClassPathById(
 411         sjme_attrInNotNull sjme_rom_suite inSuite,
 412         sjme_attrInNotNull const sjme_list_sjme_jint* inIds,
 413         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 414
 415 /**
 416  * Resolves the class path library by their name.
 417  *
 418  * @param inSuite The suite to look within.
 419  * @param inNames The names to obtain.
 420  * @param outLibs The output libraries.
 421  * @return Any resultant error state.
 422  * @since 2023/12/18
 423  */
 424 sjme_errorCode sjme_rom_resolveClassPathByName(
 425         sjme_attrInNotNull sjme_rom_suite inSuite,
 426         sjme_attrInNotNull const sjme_list_sjme_lpcstr* inNames,
 427         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 428
 429 /**
 430  * Returns all of the libraries which are available within this suite.
 431  *
 432  * @param inSuite The input suite.
 433  * @param outLibs The resultant libraries.
 434  * @return Any resultant error state.
 435  * @since 2023/12/20
 436  */
 437 sjme_errorCode sjme_rom_suiteLibraries(
 438         sjme_attrInNotNull sjme_rom_suite inSuite,
 439         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 440
 441 /*--------------------------------------------------------------------------*/
 442
 443 /* Anti-C++. */
 444 #ifdef __cplusplus
 445         #ifdef SJME_CXX_SQUIRRELJME_ROM_H
 446 }
 447                 #undef SJME_CXX_SQUIRRELJME_ROM_H
 448                 #undef SJME_CXX_IS_EXTERNED
 449         #endif /* #ifdef SJME_CXX_SQUIRRELJME_ROM_H */
 450 #endif     /* #ifdef __cplusplus */
 451
 452 #endif /* SQUIRRELJME_ROM_H */