Libndls

From Hackspire
Revision as of 18:27, 4 July 2012 by Debrouxl (talk | contribs) (Levak indicated that some issues with show_msg_user_input were fixed in SVN r634.)
Jump to navigation Jump to search

libndls is a set of macros and functions available as a static library when building with Ndless. The library is automatically linked by nspire-ld if required.

These definitions are available in Ndless 2.0. Definitions marked with (asm) are only available in assembly.

Platform

  • _TINSPIRE: since v3.1. Use #ifdef _TINSPIRE to check whether you are building with nspire-gcc (i.e. for the TI-Nspire platform).
  • 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 work without v3.1 r617 or higher.

Common types

  • typedef enum bool {FALSE = 0, TRUE = 1} BOOL;

Data manipulation

  • uint16_t bswap16(uint16_t): swap the bytes of a 2-bytes integer
  • uint32_t bswap32(uint32_t): swap the bytes of a 4-bytes integer

Math

  • number abs(number)
  • number min(number, number)
  • number max(number, number)

Screen

  • 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.

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 include/common.h.
  • BOOL on_key_pressed(void): since v3.1. Non-blocking ON key press test.
  • 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.

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.
  • (CX compatibility to come - temporarily removed) unsigned set_cpu_speed(unsigned speed): since v3.1. speed is one of CPU_SPEED_150MHZ, CPU_SPEED_120MHZ, CPU_SPEED_90MHZ. Returns the previous speed. You must restore the original speed before the program exits.

Hardware

  • BOOL is_classic: since v3.1. TRUE on classic TI-Nspire. This is the preferred way to check CX-specific features: if (is_classic) classic_code; else cx_code;
  • BOOL is_cx: since v3.1. TRUE on TI-Nspire CX.

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*.
  • volatile unsigned *IO_LCD_CONTROL: since v3.1. LCD control register of the LCD controller

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 sleep(unsigned m): delay for a specified amount of time. The CPU is regularly switched to low-power state while blocking.

Debugging

  • Deprecated since v3.1, replaced with bkpt(). void halt(void): stop the execution flow with an endless loop. If you are using the Ncubate emulator, use the j debugger command to jump over the instruction.
  • void bkpt(): software breakpoint. Make the emulator halt and open the debugger.