Feature/refactor headers

.gitignore

@@ -1,7 +1,8 @@
 # backups and ide stuff
 *~
 .idea/
-
+.vs/
+.vscode/
 
 # generated documentation
 doxygen/

docs/doxyfile

@@ -840,7 +840,26 @@ INPUT                  = ../src/graphx/graphx.h \
                          ../src/ce/debug.h \
                          ../src/ce/tice.h \
                          ../src/ce/intce.h \
-                         ../src/ce/compression.h
+                         ../src/ce/compression.h \
+                         ../src/ce/sys/basicusb.h \
+                         ../src/ce/sys/lcd.h \
+                         ../src/ce/sys/power.h \
+                         ../src/ce/sys/rtc.h \
+                         ../src/ce/sys/timers.h \
+                         ../src/ce/sys/util.h \
+                         ../src/ce/ti/debug.h \
+                         ../src/ce/ti/error.h \
+                         ../src/ce/ti/flags.h \
+                         ../src/ce/ti/getcsc.h \
+                         ../src/ce/ti/getkey.h \
+                         ../src/ce/ti/screen.h \
+                         ../src/ce/ti/hooks.h \
+                         ../src/ce/ti/info.h \
+                         ../src/ce/ti/python.h \
+                         ../src/ce/ti/real.h \
+                         ../src/ce/ti/tokens.h \
+                         ../src/ce/ti/ui.h \
+                         ../src/ce/ti/vars.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/headers/index.rst

@@ -1,7 +1,7 @@
 .. _headers:
 
 CE Toolchain Specific Headers
-===============================
+=============================
 
 These headers are CE specific, and contain various defines and prototypes.
 
@@ -12,4 +12,3 @@ These headers are CE specific, and contain various defines and prototypes.
     tice
     intce
     compression
-

docs/headers/sys/basicusb.rst

@@ -0,0 +1,20 @@
+.. _basicusb_h:
+
+sys/basicusb.h
+==============
+
+.. code-block:: c
+
+    #include <sys/basicusb.h>
+
+Proper support for USB devices is in development.
+This header does not provide that.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/basicusb.h
+   :project: CE C/C++ Toolchain

docs/headers/sys/index.rst

@@ -0,0 +1,17 @@
+.. _sys:
+
+CE Hardware Headers
+===================
+
+These headers are specific to the calculator's hardware, and contain various defines and prototypes.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    basicusb
+    lcd
+    power
+    rtc
+    timers
+    util

docs/headers/sys/lcd.rst

@@ -0,0 +1,19 @@
+.. _lcd_h:
+
+sys/lcd.h
+=========
+
+.. code-block:: c
+
+    #include <sys/lcd.h>
+
+This header includes defines for the PL111 LCD controller used in the CE.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/lcd.h
+   :project: CE C/C++ Toolchain

docs/headers/sys/power.rst

@@ -0,0 +1,20 @@
+.. _power_h:
+
+sys/power.h
+===========
+
+.. code-block:: c
+
+    #include <sys/power.h>
+
+Power control hardware registers are not directly accessible.
+However, this header provides access to OS routines that perform control functions.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/power.h
+   :project: CE C/C++ Toolchain

docs/headers/sys/rtc.rst

@@ -0,0 +1,20 @@
+.. _rtc.h:
+
+sys/rtc.h
+=========
+
+.. code-block:: c
+
+    #include <sys/rtc.h>
+
+This header includes defines for the Real-Time Clock (RTC) used in the CE.
+The toolchain allows both direct access to the hardware registers, and using TI's helper routines.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/rtc.h
+   :project: CE C/C++ Toolchain

docs/headers/sys/timers.rst

@@ -0,0 +1,21 @@
+.. _timers_h:
+
+sys/timers.h
+============
+
+.. code-block:: c
+
+    #include <sys/timers.h>
+
+This header includes defines for the CE's hardware timers.
+There are two possible timing ("clock") sources: a 32768 Hz crystal with similar accuracy to the clock found in any
+smartphone or wristwatch, and the CPU's main 48 MHz clock with likely much inferior accuracy.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/timers.h
+   :project: CE C/C++ Toolchain

docs/headers/sys/util.rst

@@ -0,0 +1,19 @@
+.. _util_h:
+
+sys/util.h
+==========
+
+.. code-block:: c
+
+    #include <sys/util.h>
+
+This header includes defines for miscellaneous CE-specific things.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: sys/util.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/debug.rst

@@ -0,0 +1,20 @@
+.. _debug:
+
+ti/debug.h
+==========
+
+.. code-block:: c
+
+    #include <ti/debug.h>
+
+TI has implemented debugging differently than CEmu does.
+This header provides access to TI's debugging API, which is not useful if you don't have their tools.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: ti/debug.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/error.rst

@@ -0,0 +1,35 @@
+.. _error:
+
+ti/error.h
+==========
+
+.. code-block:: c
+
+    #include <ti/error.h>
+
+Exceptions in languages like Python provide a structured way of handling rare error conditions.
+TI calls their implementation of this idea error handlers.
+
+When the OS encounters an unsusal condition such as divide-by-zero or out-of-memory, it looks for an active error handler.
+If no active error handlers exist, the OS will display the :code:`ERR:` screen.
+If an active error handler does exist, it gets control instead of showing the :code:`ERR:` screen.
+
+Unlike exception handlers, TI's error handlers do not differentiate between error codes; the same error handler is called for all errors.
+However, error handlers do support nesting.
+If an handler decides that it can't handle an error, it can rethrow it.
+
+.. warning::
+
+    When a TI error handler is invoked, C++ destructors **are not** run *even if the handler is outside the current scope!*
+    Therefore, you must be very careful with object creation while an error handler is active.
+
+Similarly, although the toolchain supports C++, it does *not* support C++ exceptions, and TI error handlers are not a substitute for C++ exceptions.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: ti/error.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/flags.rst

@@ -0,0 +1,21 @@
+.. _flags:
+
+ti/flags.h
+==========
+
+.. code-block:: c
+
+    #include <ti/flags.h>
+
+TI's operating system has a lot of simple state it keeps track of, such as whether 2nd has been pressed.
+These settings are stored in a structure called the system flags, and can be accessed quickly by the OS.
+Most of these flags are useful only if you need to access OS mathematical or UI functions.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: ti/flags.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/getcsc.rst

@@ -0,0 +1,52 @@
+.. _getcsc:
+
+ti/getcsc.h
+===========
+
+.. code-block:: c
+
+    #include <ti/getcsc.h>
+
+Naturally, TI's operating system also has its own keyboard driver.
+You can easily use it instead of the :code:`keypadc` library, and is particularly suited to non-game programs.
+
+The OS's interrupt handler handles the keyboard driver and caches a scancode when it detects a key press.
+You can use this scancode directly without any translation of 2nd and alpha through the :code:`os_GetCSC` function.
+
+TI-83 Premium CE
+----------------
+
+Some keys on the TI-83 Premium CE are labeled differently, and some have completely different functions.
+For convenience, there are additional equates for the TI-83 Premium CE names.
+In the table below, the five keys with different functions are **emphasized.**
+
++---------------+-------------------+-----------------------+-------------------------+
+| TI-84 Plus CE | Equate            | TI-83 Premium CE      | Equate                  |
++===============+===================+=======================+=========================+
+| Y=            | :code:`sk_Yequ`   | f(x)                  | :code:`sk_Fx`           |
++---------------+-------------------+-----------------------+-------------------------+
+| Window        | :code:`sk_Window` | Fenetre               | :code:`sk_Fenetre`      |
++---------------+-------------------+-----------------------+-------------------------+
+| Del           | :code:`sk_Del`    | Suppr                 | :code:`sk_Suppr`        |
++---------------+-------------------+-----------------------+-------------------------+
+| **Apps**      | :code:`sk_Apps`   | **Matrice**           | :code:`sk_Matrice`      |
++---------------+-------------------+-----------------------+-------------------------+
+| Clear         | :code:`sk_Clear`  | Annul                 | :code:`sk_Annul`        |
++---------------+-------------------+-----------------------+-------------------------+
+| **x^-1**      | :code:`sk_Recip`  | **<>**                | :code:`sk_TglExact`     |
++---------------+-------------------+-----------------------+-------------------------+
+| **Sin**       | :code:`sk_Sin`    | **Trig**              | :code:`sk_Trig`         |
++---------------+-------------------+-----------------------+-------------------------+
+| **Cos**       | :code:`sk_Cos`    | **Resol**             | :code:`sk_Resol`        |
++---------------+-------------------+-----------------------+-------------------------+
+| **Tan**       | :code:`sk_Tan`    | **Fraction template** | :code:`sk_Frac`         |
++---------------+-------------------+-----------------------+-------------------------+
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: ti/getcsc.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/getkey.rst

@@ -0,0 +1,26 @@
+.. _getkey:
+
+ti/getkey.h
+===========
+
+.. code-block:: c
+
+    #include <ti/getkey.h>
+
+For programs that interact with the OS's user interface, you may want to use processed keystrokes instead of raw scancodes.
+The :code:`os_GetKey` routine handles 2nd and alpha presses, and can even show menus.
+
+TI-83 Premium CE
+----------------
+
+No research has been done on how the TI-83 Premium CE is different here.
+However, you should be aware that on the TI-83 Premium CE, :code:`os_GetKey` may return values not included in this list.
+
+.. contents:: :local:
+   :depth: 3
+
+API Documentation
+-----------------
+
+.. doxygenfile:: ti/getkey.h
+   :project: CE C/C++ Toolchain

docs/headers/ti/index.rst

@@ -0,0 +1,29 @@
+.. _ti:
+
+TI Operating System Headers
+===========================
+
+These headers are specific to functionality provided by the calculator's operating system, and contain various defines and prototypes.
+
+TI used to provide a free SDK for the TI-83 Plus, which is now no longer available.
+However, the TI-84 Plus CE software is directly derived from the TI-83 Plus software,
+so we do have a lot of official, though dated, information.
+This is also why names are inconsistent: sometimes TI's names don't follow a pattern, and other times,
+whoever in the community first discovered something gave it a name following their own logic.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    debug
+    error
+    flags
+    getcsc
+    getkey
+    screen
+    info
+    python
+    real
+    tokens
+    ui
+    vars