//Pascal &or the FreePascal use of nintendo 2ds, 3ds regime
//
// Copyright (c) 2013, 2015, 2017 Kenneth Dwayne Lee Bsc.
// all rights reserved
//

  {*
   * @file errf.h
   * @brief Error Display API
    }

  {/ Types of errors that can be thrown by err:f. }
  {/< For generic errors. Shows miscellaneous info. }
  {/< Same output as generic, but informs the user that "the System Memory has been damaged". }
  {/< Displays the "The Game Card was removed." message. }
  {/< For exceptions, or more specifically 'crashes'. union data should be exception_data. }
  {/< For general failure. Shows a message. union data should have a string set in failure_mesg }
  {/< Outputs logs to NAND in some cases. }

  type

     ERRF_ErrType = (ERRF_ERRTYPE_GENERIC := 0,ERRF_ERRTYPE_MEM_CORRUPT := 1,
       ERRF_ERRTYPE_CARD_REMOVED := 2,ERRF_ERRTYPE_EXCEPTION := 3,
       ERRF_ERRTYPE_FAILURE := 4,ERRF_ERRTYPE_LOGGED := 5
       );
  {/ Types of 'Exceptions' thrown for ERRF_ERRTYPE_EXCEPTION }
  {/< Prefetch Abort }
  {/< Data abort }
  {/< Undefined instruction }
  {/< VFP (floating point) exception. }

     ERRF_ExceptionType = (ERRF_EXCEPTION_PREFETCH_ABORT := 0,
       ERRF_EXCEPTION_DATA_ABORT := 1,ERRF_EXCEPTION_UNDEFINED := 2,
       ERRF_EXCEPTION_VFP := 3);
  {/< Type of the exception. One of the ERRF_EXCEPTION_* values. }
  {/< If type is prefetch, this should be ifsr, and on data abort dfsr }
  {/< If type is prefetch, this should be r15, and dfar on data abort }

     ERRF_ExceptionInfo = record
          _type : ERRF_ExceptionType;
          reserved : array[0..2] of u8;
          reg1 : u32;
          reg2 : u32;
          fpexc : u32;
          fpinst : u32;
          fpint2 : u32;
       end;
  {/< Exception info struct }
  
  {/< CPU register dump. }
  
     CpuRegisters = record
          r : array[0..2] of u32;
          sp : u32;
          lr : u32;
          sc : u32;
          cpsr : u32;
       end;
       
     ERRF_ExceptionData = record
          excep : ERRF_ExceptionInfo;
          regs : CpuRegisters;
          pad : array[0..3] of u8;
       end;       

  {/< Type, one of the ERRF_ERRTYPE_* enum }
  {/< High revison ID }
  {/< Low revision ID }
  {/< Result code }
  {/< PC address at exception }
  {/< Process ID. }
  {/< Title ID. }
  {/< Application Title ID. }
  {/< Data for when type is ERRF_ERRTYPE_EXCEPTION }
  {/< String for when type is ERRF_ERRTYPE_FAILURE }
  {/< The different types of data for errors. }

     ERRF_FatalErrInfo = record
          _type : ERRF_ErrType;
          revHigh : u8;
          revLow : u16;
          resCode : u32;
          pcAddr : u32;
          procId : u32;
          titleId : u64;
          appTitleId : u64;
          data : record
              case longint of
                 0 : ( exception_data : ERRF_ExceptionData );
                 1 : ( failure_mesg : array[0..59] of cchar );
              end;
       end;
  {/ Initializes ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this. }

  function errfInit:s32;cdecl;external;

  {/ Exits ERR:f. Unless you plan to call ERRF_Throw yourself, do not use this. }
  procedure errfExit;cdecl;external;

  {*
   * @brief Gets the current err:f API session handle.
   * @return The current err:f API session handle.
    }
  function errfGetSessionHandle:PHandle;cdecl;external;

  {*
   * @brief Throws a system error and possibly results in ErrDisp triggering.
   * @param[in] error Error to throw.
   *
   * After performing this, the system may panic and need to be rebooted. Extra information will be displayed on the
   * top screen with a developer console or the proper patches in a CFW applied.
   *
   * The error may not be shown and execution aborted until errfExit(void) is called.
   *
   * You may wish to use ERRF_ThrowResult() or ERRF_ThrowResultWithMessage() instead of
   * constructing the ERRF_FatalErrInfo struct yourself.
    }
    
  function ERRF_Throw(error:ERRF_FatalErrInfo):s32;cdecl;external;

  {*
   * @brief Throws a system error with the given Result code.
   * @param[in] failure Result code to throw.
   *
   * This calls ERRF_Throw() with error type ERRF_ERRTYPE_GENERIC and fills in the required data.
   *
   * This function \em does fill in the address where this function was called from.
   *
   * See https://3dbrew.org/wiki/ERR:Throw#Generic for expected top screen output
   * on development units/patched ErrDisp.
    }
  function ERRF_ThrowResult(failure:s32):s32;cdecl;external;

  {*
   * @brief Throws a system error with the given Result code and message.
   * @param[in] failure Result code to throw.
   * @param[in] message The message to display.
   *
   * This calls ERRF_Throw() with error type ERRF_ERRTYPE_FAILURE and fills in the required data.
   *
   * This function does \em not fill in the address where this function was called from because it
   * would not be displayed.
   *
   * The message is only displayed on development units/patched ErrDisp.
   *
   * See https://3dbrew.org/wiki/ERR:Throw#Result_Failure for expected top screen output
   * on development units/patched ErrDisp.
    }
  function ERRF_ThrowResultWithMessage(failure:s32; message:pchar):s32;cdecl;external;