

gint.h 4.9KB

  1. //---
  2. // gint - An alternative runtime environment for fx9860g and fxcg50
  3. //---
  4. #ifndef GINT_GINT
  5. #define GINT_GINT
  6. #include <gint/defs/types.h>
  7. /* GINT_VERSION - the library version number
  8. gint is versioned from its repository commits on the master branch. The
  9. GINT_VERSION integer contains the short commit hash.
  10. For instance, 0x03f7c0a0 means commit 3f7c0a0. */
  11. extern char GINT_VERSION;
  12. #define GINT_VERSION ((uint32_t)&GINT_VERSION)
  13. //---
  14. // Library management
  15. //---
  16. /* gint_install() - install and start gint
  17. This function installs event handlers, masks interrupts and switches VBR.
  18. Unless you are doing experimental runtime switching and you know how this
  19. function is implemented, you should not call it. */
  20. void gint_install(void);
  21. /* gint_unload() - unload gint and give back control to the system
  22. This function restores the runtime environment saved by gint_install(). It
  23. is only called when the add-in terminates. To temporarily leave gint during
  24. execution, use gint_pause(). When possible, use syscalls without leaving
  25. gint for better performance. */
  26. void gint_unload(void);
  27. /* gint_pause() - return to main menu, with possibility of coming back
  28. This function safely invokes the calculator's main menu by unloading gint.
  29. If the user selects the gint application again in the menu, this function
  30. reloads gint and returns. Otherwise, the add-in is fully unloaded by the
  31. system and the application terminates.
  32. This function is typically called when the [MENU] key is pressed during a
  33. getkey() call. */
  34. void gint_pause(void);
  35. //---
  36. // Public functions
  37. //---
  38. /* gint_intlevel() - configure the level of interrupts
  39. This function changes the interrupt level of the requested interrupt. Make
  40. sure you are aware of interrupt assignments to avoid breaking other code.
  41. This function is mainly used by drivers to enable the interrupts that they
  42. support.
  43. The first parameter 'intid' identifies an interrupt by its position in the
  44. sequence:
  45. IPRA & 0xf000 ; IPRA & 0x0f00 .. IPRA & 0x000f ; IPRB & 0xf000 ..
  46. For instance ID 7 refers to the low nibble of IPRB. These IDs and the range
  47. for which there are valid is heavily platform-dependent and any call to this
  48. function should be wrapped inside an MPU type check. This function will
  49. crash if the provided interrupt ID is invalid.
  50. The interrupt level should be in the range 0 (disabled) .. 15 (highest
  51. priority).
  52. @intid Interrupt ID of the targeted interrupt
  53. @level Requested interrupt level
  54. Returns the interrupt level that was assigned before the call. */
  55. int gint_intlevel(int intid, int level);
  56. /* gint_inthandler() - configure interrupt handlers
  57. This function installs (copies) interrupt handlers in the VBR space of the
  58. application. Each handler is a 32-byte block aligned on a 32-byte boundary.
  59. When an interrupt request is accepted, the hardware jumps to a specific
  60. interrupt handler at an address that depends on the interrupt source.
  61. For safety, interrupt handlers should avoir referring to data from other
  62. blocks because the arrangement of blocks at runtime depends on event codes.
  63. The assembler program will assume that consecutive blocks in the source code
  64. will be consecutive in memory, which is not always true. Avoiding cross-
  65. references is a practical rule to avoid problems. (gint breaks this rule
  66. very often but does it carefully... I guess?)
  67. This function allows anyone to replace any interrupt handler so make sure
  68. you're not interfering with usual interrupt assignments.
  69. The first parameter 'event_code' represents the event_code associated with
  70. the interrupt. If it's not a multiple of 0x20 then you're doing something
  71. wrong. The codes are normally platform-dependent, but gint always uses
  72. SH7305 codes: SH3 platforms have a translation table. See the documentation
  73. for a list of event codes and their associated interrupts.
  74. The handler function must be an interrupt handler: it must not raise
  75. exceptions, must end with 'rte', and it will use the kernel register bank.
  76. For convenience I allow any block size to be loaded as an interrupt handler,
  77. but it should really be a multiple of 0x20 bytes and not override other
  78. handlers. If it's not written in assembler, then you're likely doing
  79. something wrong, even with __attribute__((interrupt_handler)).
  80. It is common for interrupt handlers to have a few bytes of data, such as the
  81. address of a callback function. gint often stores this data in the last
  82. bytes of the block. This function returns the VBR address of the block to
  83. allow the caller to edit the parameters.
  84. @event_code Identifier of the interrupt block
  85. @handler Address of handler function
  86. @size How many bytes to copy
  87. Returns the VBR address where the handlers was installed. */
  88. void *gint_inthandler(int event_code, const void *handler, size_t size);
  89. #endif /* GINT_GINT */