Libndls: Difference between revisions

From Hackspire
Jump to navigation Jump to search
m (Minor changes)
No edit summary
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
''libndls'' is a set of macros and functions available as a [http://en.wikipedia.org/wiki/Static_library static library] when building with Ndless. The library is automatically linked by <tt>nspire-ld</tt> and <tt>nspire-ld-bflt</tt> if required.
''libndls'' is a set of macros and functions available as a [https://en.wikipedia.org/wiki/Static_library static library] when building with Ndless. The library is automatically linked by <tt>nspire-gcc</tt> and <tt>nspire-g++</tt> without "-nostdlib".


These definitions are available in Ndless 3.1. Definitions marked with (asm) are only available in assembly.
These definitions are available in the latest version of the Ndless SDK and should work on every Ndless version.
 
==Platform==
*<tt>_TINSPIRE</tt>: since v3.1. Use <tt>#ifdef _TINSPIRE</tt> to check whether you are building with nspire-gcc (i.e. for the TI-Nspire platform).
*<tt>void assert_ndless_rev(unsigned required_rev)</tt>: Since v3.1 r617. Displays a popup asking to update Ndless if the Ndless revision on the calculator is less than ''required_rev'', and exits the program. Does nothing if the revision is greater or equal than ''required_rev''. You should call this function at the beginning of your program if it is using syscalls recently added to Ndless, or libndls functions which depend on recent syscalls. See [[Ndless_features_and_limitations#Checking Ndless's version|Checking Ndless version]] for more info. Note that this function work without v3.1 r617 or higher.


==Ndless==
==Ndless==
*<tt>const char *NDLESS_DIR</tt>: (since v3.1 r797) fullpath to the "ndless/" directory in the documents folder.
*<tt>void assert_ndless_rev(unsigned required_rev)</tt>: Since v3.1 r617. Displays a popup asking to update Ndless if the Ndless revision on the calculator is less than ''required_rev'', and exits the program. Does nothing if the revision is greater or equal than ''required_rev''. You should call this function at the beginning of your program if it is using syscalls recently added to Ndless, or libndls functions which depend on recent syscalls. See [[Ndless_features_and_limitations#Checking Ndless's version|Checking Ndless version]] for more info. Note that this function works without v3.1 r617 or higher.
 
*<tt>const char *NDLESS_DIR</tt>: (since v3.1 r797) full path to the "ndless" directory in the documents folder ("/documents/ndless")
==Common types==
*<tt>typedef enum bool {FALSE = 0, TRUE = 1} BOOL;</tt>
 
==Data manipulation==
*<tt>uint16_t bswap16(uint16_t)</tt>: swap the bytes of a 2-bytes integer
*<tt>uint32_t bswap32(uint32_t)</tt>: swap the bytes of a 4-bytes integer


==Math==
==LCD API==
*<tt>number abs(number)</tt>
*<tt>scr_type_t lcd_type()</tt>: Returns the native LCD type (see the list below). Using this is always the fastest way to display a frame.
*<tt>number min(number, number)</tt>
*<tt>bool lcd_init(scr_type_t type)</tt>: Set the LCD mode. You need to call this before you can use lcd_blit with the same <tt>scr_type</tt>. You also need to call <tt>lcd_init(SCR_TYPE_INVALID)</tt> before using any of the functions in the UI section and before exiting the program.
*<tt>number max(number, number)</tt>
*<tt>void lcd_blit(void* buffer, scr_type_t type)</tt>: Blit the buffer to the screen.


==Screen==
Available screen types (as of r2004):
*<tt>SCREEN_BASE_ADDRESS</tt>: address of the screen buffer. Read from the LCD controller, caching it is recommended.
*SCR_320x240_4: 4bit grayscale. Native on classic calcs.
*<tt>SCREEN_BYTES_SIZE</tt>: size of the screen buffer. Calculated depending on the color mode advertised by the LCD controller, caching it is recommended as long as the mode isn't changed.
*SCR_320x240_8: 8bit paletted mode.
*<tt>SCREEN_WIDTH</tt>: screen width in pixels
*SCR_320x240_16: RGB444
*<tt>SCREEN_HEIGHT</tt>: screen height in pixels
*SCR_320x240_565: RGB565. Native on CX before HW-W
*<tt>void clrscr(void)</tt>: clear the screen
*SCR_240x320_565: RGB565. Native on CX HW-W
*<tt>BOOL lcd_isincolor(void)</tt>: since v3.1. Check the current LCD mode.
*<tt>void lcd_incolor(void)</tt>: since v3.1. Switch to color LCD mode.
*<tt>void lcd_ingray(void)</tt>: since v3.1. Switch to grayscale LCD mode.


==UI==
==UI==
Line 43: Line 30:
==Keyboard==
==Keyboard==
*<tt>BOOL any_key_pressed(void)</tt>: non-blocking key press test. Return <tt>TRUE</tt> if one or more keys are being pressed.
*<tt>BOOL any_key_pressed(void)</tt>: non-blocking key press test. Return <tt>TRUE</tt> if one or more keys are being pressed.
*<tt>BOOL isKeyPressed(key)</tt>: non-blocking key press test. <tt>key</tt> must be one of the <tt>KEY_NSPIRE_*</tt> constants defined in ''ndless/include/common.h''.
*<tt>BOOL isKeyPressed(key)</tt>: non-blocking key press test. <tt>key</tt> must be one of the <tt>KEY_NSPIRE_*</tt> constants defined in keys.h.
*<tt>BOOL on_key_pressed(void)</tt>: since v3.1. Non-blocking ON key press test.
*<tt>BOOL on_key_pressed(void)</tt>: since v3.1. Non-blocking ON key press test. Caution, key scanning is time consuming and may hurt the performance of programs which needs high reactivity. You should skip key scanning regularly in the main loop of a game.
*<tt>void wait_key_pressed(void)</tt>: block until a key is pressed. Changing the timer frequency have effects on the latency of this function.
*<tt>void wait_key_pressed(void)</tt>: block until a key is pressed. Changing the timer frequency have effects on the latency of this function.
*<tt>void wait_no_key_pressed(void)</tt>: block until all the keys are released. Changing the timer frequency have effects on the latency of this function.
*<tt>void wait_no_key_pressed(void)</tt>: block until all the keys are released. Changing the timer frequency have effects on the latency of this function.
*<tt>touchpad_info_t *touchpad_getinfo(void)</tt>: return information on the Touchpad area such as its dimension. Return <tt>NULL</tt> if not a TI-Nspire Touchpad. See <tt>include/libndls.h</tt> for the definition of <tt>touchpad_info_t</tt>.
*<tt>touchpad_info_t *touchpad_getinfo(void)</tt>: return information on the Touchpad area such as its dimension. Return <tt>NULL</tt> if not a TI-Nspire Touchpad. See <tt>include/libndls.h</tt> for the definition of <tt>touchpad_info_t</tt>.
*<tt>int touchpad_scan(touchpad_report_t *report)</tt>: check user interactions with the Touchpad area and writes to <tt>report</tt>. See <tt>include/libndls.h</tt> for the definition of <tt>touchpad_report_t</tt>. <tt>report->contact</tt> and <tt>report->pressed</tt> are always <tt>FALSE</tt> on TI-Nspire Clickpad. See <tt>src/arm/tests/ndless_tpad.c</tt> for an example of use.
*<tt>int touchpad_scan(touchpad_report_t *report)</tt>: check user interactions with the Touchpad area and writes to <tt>report</tt>. See <tt>include/libndls.h</tt> for the definition of <tt>touchpad_report_t</tt>. <tt>report->contact</tt> and <tt>report->pressed</tt> are always <tt>FALSE</tt> on TI-Nspire Clickpad. See <tt>src/arm/tests/ndless_tpad.c</tt> for an example of use.
*<tt>int get_event(struct s_ns_event*)</tt>: since r721. Poll for an OS event. See <tt>struct s_ns_event</tt> in os.h.
*<tt>int get_event(struct s_ns_event*)</tt>: since r721. Poll for an OS event. See <tt>struct s_ns_event</tt> in nucleus.h.
*<tt>void send_key_event struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r721. Simulate a key event.
*<tt>void send_key_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r721. Simulate a key event.
*<tt>void send_click_event struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r750. Simulate a click event. keycode_asciicode=0xFB00: single click, keycode_asciicode=0xAC00: drag.
*<tt>void send_click_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r750. Simulate a click event. keycode_asciicode=0xFB00: single click, keycode_asciicode=0xAC00: drag.
*<tt>void send_pad_event struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r750. Simulate a cursor move. Set the cursor coordinates in eventbuf, and keycode_asciicode to 0x7F00.
*<tt>void send_pad_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown)</tt>: since r750. Simulate a cursor move. Set the cursor coordinates in eventbuf, and keycode_asciicode to 0x7F00.


==Filesystem==
==Filesystem==
Line 59: Line 46:
==CPU==
==CPU==
*<tt>void clear_cache(void)</tt>: flush the data cache and invalidate the instruction and data caches of the processor. Should be called before loading code dynamically, after a code patch or with self-modifying code.
*<tt>void clear_cache(void)</tt>: flush the data cache and invalidate the instruction and data caches of the processor. Should be called before loading code dynamically, after a code patch or with self-modifying code.
*(CX compatibility to come - temporarily removed) <del><tt>unsigned set_cpu_speed(unsigned speed)</tt>: since v3.1. ''speed'' is one of <tt>CPU_SPEED_150MHZ</tt>, <tt>CPU_SPEED_120MHZ</tt>, <tt>CPU_SPEED_90MHZ</tt>. Returns the previous speed. You must restore the original speed before the program exits.</del>


==Hardware==
==Hardware==
*<tt>BOOL is_classic</tt>: since v3.1. <tt>TRUE</tt> on classic TI-Nspire. This is the preferred way to check CX-specific features: ''if (is_classic) classic_code; else cx_code;''
*<tt>BOOL is_classic</tt>: since v3.1. <tt>TRUE</tt> on classic TI-Nspire. This is the preferred way to check CX/CM-specific features: ''if (is_classic) classic_code; else cx_code;''
*<tt><strike>BOOL is_cx</strike></tt>: deprecated since r863, use <tt>has_colors</tt>.
*<tt>BOOL is_cm</tt>: since v3.1 r863. <tt>TRUE</tt> on TI-Nspire CM/CM-C.
*<tt>BOOL is_cm</tt>: since v3.1 r863. <tt>TRUE</tt> on TI-Nspire CM/CM-C.
*<tt>BOOL has_colors</tt>: since v3.1. <tt>TRUE</tt> if the device has a screen in color.
*<tt>BOOL has_colors</tt>: since v3.1. <tt>TRUE</tt> if the device has a screen in color.
Line 69: Line 54:
*<tt>unsigned hwtype()</tt>: 0 on classic TI-Nspire, 1 on TI-Nspire CX.
*<tt>unsigned hwtype()</tt>: 0 on classic TI-Nspire, 1 on TI-Nspire CX.
*<tt>IO()</tt>: select an I/O port whose mapping depends on the hardware type. Fo example <tt>IO(0xDC00000C, 0xDC0000010)</tt> will return 0xDC00000C on classic TI-Nspire, 0xDC0000010 on CX. Returns a ''volatile unsigned*''.
*<tt>IO()</tt>: select an I/O port whose mapping depends on the hardware type. Fo example <tt>IO(0xDC00000C, 0xDC0000010)</tt> will return 0xDC00000C on classic TI-Nspire, 0xDC0000010 on CX. Returns a ''volatile unsigned*''.
*<tt>volatile unsigned *IO_LCD_CONTROL</tt>: since v3.1. LCD control register of the LCD controller


==Time==
==Time==
*<tt>void idle(void)</tt>: switch to low-power state until the next interrupt occurs. The use of this function is encouraged when waiting in loops for an event to save the batteries.  Changing the timer frequency have effects on the latency of this function.
*<tt>void idle(void)</tt>: switch to low-power state until the next interrupt occurs. The use of this function is encouraged when waiting in loops for an event to save the batteries.  Changing the timer frequency have effects on the latency of this function.
*<tt>void sleep(unsigned m)</tt>: delay for a specified amount of time in ms. The CPU is regularly switched to low-power state while blocking.
*<tt>void msleep(unsigned ms)</tt>: delay for a specified amount of time in ms. The CPU is regularly switched to low-power state while blocking. Note that the <tt>sleep</tt> function has been removed.


==Configuration==
==Configuration==
Line 79: Line 63:


==Debugging==
==Debugging==
*Deprecated since v3.1, replaced with bkpt(). <del><tt>void halt(void)</tt>: stop the execution flow with an endless loop. If you are using the [http://www.omnimaga.org/index.php?topic=4280.0 Ncubate] emulator, use the <tt>j</tt> debugger command to jump over the instruction.</del>
*<tt>void bkpt()</tt>: software breakpoint. Make the emulator halt and open the debugger. Remove before transferring to a calculator, as it will crash if executed.
*<tt>void bkpt()</tt>: software breakpoint. Make the emulator halt and open the debugger.
 
==Deprecated==
===Common types===
Deprecated. Use #include <stdbool.h> instead.
<tt>typedef enum bool {FALSE = 0, TRUE = 1} BOOL;</tt>
 
===Old screen API===
The following section is only valid if using the OLD_SCREEN_API define.
 
*<tt>SCREEN_BASE_ADDRESS</tt>: address of the screen buffer. Read from the LCD controller, caching it is recommended.
*<tt>SCREEN_BYTES_SIZE</tt>: size of the screen buffer. Calculated depending on the color mode advertised by the LCD controller, caching it is recommended as long as the mode isn't changed.
*<tt>SCREEN_WIDTH</tt>: screen width in pixels
*<tt>SCREEN_HEIGHT</tt>: screen height in pixels
*<tt>void clrscr(void)</tt>: clear the screen
*<tt>BOOL lcd_isincolor(void)</tt>: since v3.1. Check the current LCD mode.
*<tt>void lcd_incolor(void)</tt>: since v3.1. Switch to color LCD mode.
*<tt>void lcd_ingray(void)</tt>: since v3.1. Switch to grayscale LCD mode.
*<tt>volatile unsigned *IO_LCD_CONTROL</tt>: since v3.1. LCD control register of the LCD controller

Latest revision as of 14:36, 21 June 2019

libndls is a set of macros and functions available as a static library when building with Ndless. The library is automatically linked by nspire-gcc and nspire-g++ without "-nostdlib".

These definitions are available in the latest version of the Ndless SDK and should work on every Ndless version.

Ndless

  • void assert_ndless_rev(unsigned required_rev): Since v3.1 r617. Displays a popup asking to update Ndless if the Ndless revision on the calculator is less than required_rev, and exits the program. Does nothing if the revision is greater or equal than required_rev. You should call this function at the beginning of your program if it is using syscalls recently added to Ndless, or libndls functions which depend on recent syscalls. See Checking Ndless version for more info. Note that this function works without v3.1 r617 or higher.
  • const char *NDLESS_DIR: (since v3.1 r797) full path to the "ndless" directory in the documents folder ("/documents/ndless")

LCD API

  • scr_type_t lcd_type(): Returns the native LCD type (see the list below). Using this is always the fastest way to display a frame.
  • bool lcd_init(scr_type_t type): Set the LCD mode. You need to call this before you can use lcd_blit with the same scr_type. You also need to call lcd_init(SCR_TYPE_INVALID) before using any of the functions in the UI section and before exiting the program.
  • void lcd_blit(void* buffer, scr_type_t type): Blit the buffer to the screen.

Available screen types (as of r2004):

  • SCR_320x240_4: 4bit grayscale. Native on classic calcs.
  • SCR_320x240_8: 8bit paletted mode.
  • SCR_320x240_16: RGB444
  • SCR_320x240_565: RGB565. Native on CX before HW-W
  • SCR_240x320_565: RGB565. Native on CX HW-W

UI

  • void show_msgbox(const char *title, const char *msg): show a message box, with a single button OK"
  • unsigned int show_msgbox_2b(const char *title, const char *msg, const char *button1, const char *button2): since v3.1. show a message box with two buttons with custom labels. Return the number of the button pressed (1 for the first button).
  • unsigned int show_msgbox_3b(const char *title, const char *msg, const char *button1, const char *button2, const char *button3): since v3.1. show a message box with three buttons with custom labels. Return the number of the button pressed (1 for the first button).
  • int show_msg_user_input(const char * title, const char * msg, char * defaultvalue, char ** value_ref): since v3.1 r607. Request popup. Usage: char * value; show_msg_user_input("title", "msg", "default", &value). value must be freed with free() once used. Returns the length of the value, or -1 if an empty text was entered or escape was pressed. Some issues fixed in r634 with the new String API.
  • int show_1numeric_input(const char * title, const char * subtitle, const char * msg, int * value_ref, int min_value, int max_value): since v3.1 r607. Request popup for one numeric input. Caution, values like -1 or 0 for min_value will cancel the popup. Returns 1 if OK, 0 if cancelled.
  • int show_2numeric_input(const char * title, const char * subtitle, const char * msg1, int * value1_ref, int min_value1, int max_value1, const char * msg2, int * value2_ref, int min_value2, int max_value2): since v3.1 r607. Request popup for two numeric inputs. Caution, values like -1 or 0 for min_value will cancel the popup. Returns 1 if OK, 0 if cancelled.
  • void refresh_osscr(void): since v3.1. Must be called at the end of a program that creates or deletes files, to update the OS document browser.

Keyboard

  • BOOL any_key_pressed(void): non-blocking key press test. Return TRUE if one or more keys are being pressed.
  • BOOL isKeyPressed(key): non-blocking key press test. key must be one of the KEY_NSPIRE_* constants defined in keys.h.
  • BOOL on_key_pressed(void): since v3.1. Non-blocking ON key press test. Caution, key scanning is time consuming and may hurt the performance of programs which needs high reactivity. You should skip key scanning regularly in the main loop of a game.
  • void wait_key_pressed(void): block until a key is pressed. Changing the timer frequency have effects on the latency of this function.
  • void wait_no_key_pressed(void): block until all the keys are released. Changing the timer frequency have effects on the latency of this function.
  • touchpad_info_t *touchpad_getinfo(void): return information on the Touchpad area such as its dimension. Return NULL if not a TI-Nspire Touchpad. See include/libndls.h for the definition of touchpad_info_t.
  • int touchpad_scan(touchpad_report_t *report): check user interactions with the Touchpad area and writes to report. See include/libndls.h for the definition of touchpad_report_t. report->contact and report->pressed are always FALSE on TI-Nspire Clickpad. See src/arm/tests/ndless_tpad.c for an example of use.
  • int get_event(struct s_ns_event*): since r721. Poll for an OS event. See struct s_ns_event in nucleus.h.
  • void send_key_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown): since r721. Simulate a key event.
  • void send_click_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown): since r750. Simulate a click event. keycode_asciicode=0xFB00: single click, keycode_asciicode=0xAC00: drag.
  • void send_pad_event(struct s_ns_event* eventbuf, unsigned short keycode_asciicode, BOOL is_key_up, BOOL unknown): since r750. Simulate a cursor move. Set the cursor coordinates in eventbuf, and keycode_asciicode to 0x7F00.

Filesystem

int enable_relative_paths(char **argv): since r820. Call before using fopen() and other file-related functions with paths relative to the current program. argv should be the argv parameter of the main() function. Returns -1 on error, 0 if success.

CPU

  • void clear_cache(void): flush the data cache and invalidate the instruction and data caches of the processor. Should be called before loading code dynamically, after a code patch or with self-modifying code.

Hardware

  • BOOL is_classic: since v3.1. TRUE on classic TI-Nspire. This is the preferred way to check CX/CM-specific features: if (is_classic) classic_code; else cx_code;
  • BOOL is_cm: since v3.1 r863. TRUE on TI-Nspire CM/CM-C.
  • BOOL has_colors: since v3.1. TRUE if the device has a screen in color.
  • BOOL is_touchpad: TRUE on a TI-Nspire Touchpad or on a TI-Nspire CX.
  • unsigned hwtype(): 0 on classic TI-Nspire, 1 on TI-Nspire CX.
  • IO(): select an I/O port whose mapping depends on the hardware type. Fo example IO(0xDC00000C, 0xDC0000010) will return 0xDC00000C on classic TI-Nspire, 0xDC0000010 on CX. Returns a volatile unsigned*.

Time

  • void idle(void): switch to low-power state until the next interrupt occurs. The use of this function is encouraged when waiting in loops for an event to save the batteries. Changing the timer frequency have effects on the latency of this function.
  • void msleep(unsigned ms): delay for a specified amount of time in ms. The CPU is regularly switched to low-power state while blocking. Note that the sleep function has been removed.

Configuration

  • void cfg_register_fileext(const char *ext, const char *prgm): (since v3.1 r797) associate for Ndless the file extension ext (without leading '.') to the program name prgm. Does nothing if the extension is already registered.

Debugging

  • void bkpt(): software breakpoint. Make the emulator halt and open the debugger. Remove before transferring to a calculator, as it will crash if executed.

Deprecated

Common types

Deprecated. Use #include <stdbool.h> instead. typedef enum bool {FALSE = 0, TRUE = 1} BOOL;

Old screen API

The following section is only valid if using the OLD_SCREEN_API define.

  • SCREEN_BASE_ADDRESS: address of the screen buffer. Read from the LCD controller, caching it is recommended.
  • SCREEN_BYTES_SIZE: size of the screen buffer. Calculated depending on the color mode advertised by the LCD controller, caching it is recommended as long as the mode isn't changed.
  • SCREEN_WIDTH: screen width in pixels
  • SCREEN_HEIGHT: screen height in pixels
  • void clrscr(void): clear the screen
  • BOOL lcd_isincolor(void): since v3.1. Check the current LCD mode.
  • void lcd_incolor(void): since v3.1. Switch to color LCD mode.
  • void lcd_ingray(void): since v3.1. Switch to grayscale LCD mode.
  • volatile unsigned *IO_LCD_CONTROL: since v3.1. LCD control register of the LCD controller