Libndls and Ndless: Difference between pages

From Hackspire
(Difference between pages)
Jump to navigation Jump to search
No edit summary
 
No edit summary
 
Line 1: Line 1:
''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".
��Ndless combines a resident program and utilities to open the TI-Nspire to third-party C and assembly development. Ndless is distributed under the Open Source [https://en.wikipedia.org/wiki/Mozilla_Public_License Mozilla Public License].


These definitions are available in the latest version of the Ndless SDK and should work on every Ndless version.
The installation of Ndless on a TI-Nspire is required to be able to run [[Assembly_programs|assembly programs]].


==Ndless==
Find help for any Ndless related question or issues on the [https://github.com/ndless-nspire/Ndless/issues issue tracker].
*<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")


==LCD API==
'''[http://ndless.me/ Latest stable release]
*<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>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>void lcd_blit(void* buffer, scr_type_t type)</tt>: Blit the buffer to the screen.


Available screen types (as of r2004):
==Developing with Ndless==
*SCR_320x240_4: 4bit grayscale. Native on classic calcs.
Tutorials and general information are available in the [[Main_Page#Development_resources|Development resources]] section.
*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==
===Version upgrade===
*<tt>void show_msgbox(const char *title, const char *msg)</tt>: show a message box, with a single button OK"
The executable format, the conventions and the header files are currently being defined and prone to change. Some changes are forced by This section describes the upgrade steps between the different releases of Ndless.
*<tt>unsigned int show_msgbox_2b(const char *title, const char *msg, const char *button1, const char *button2)</tt>: 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).
*<tt>unsigned int show_msgbox_3b(const char *title, const char *msg, const char *button1, const char *button2, const char *button3)</tt>: 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).
*<tt>int show_msg_user_input(const char * title, const char * msg, char * defaultvalue, char ** value_ref)</tt>: since v3.1 r607. Request popup. Usage: <tt>char * value; show_msg_user_input("title", "msg", "default", &value)</tt>. <tt>value</tt> must be freed with <tt>free()</tt> 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.
*<tt>int show_1numeric_input(const char * title, const char * subtitle, const char * msg, int * value_ref, int min_value, int max_value)</tt>: 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.
*<tt>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)</tt>: 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.
*<tt>void refresh_osscr(void)</tt>: since v3.1. Must be called at the end of a program that creates or deletes files, to update the OS document browser.


==Keyboard==
====To v4.4 r2005====
*<tt>BOOL any_key_pressed(void)</tt>: non-blocking key press test. Return <tt>TRUE</tt> if one or more keys are being pressed.
*Should work directly for most programs if they don't contain any OS-version specific addresses (SYSCALL_CUSTOM(), hooks, etc.)
*<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. 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_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>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 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_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.


==Filesystem==
====To v4.2 r2004====
<tt>int enable_relative_paths(char **argv)</tt>: since r820. Call before using <tt>fopen()</tt> and other file-related functions with paths relative to the current program. <tt>argv</tt> should be the <tt>argv</tt> parameter of the <tt>main()</tt> function. Returns -1 on error, 0 if success.
*HW rev. W introduced a new 240x320px screen which breaks most Ndless programs.
*A new API to make use of the different screen is now available, SCREEN_BASE_ADDRESS is only available in OLD_SCREEN_API (Add the define to the compile options) mode. See [[Libndls#LCD_API|LCD API]] for information about the new API.
*Nspire I/O and nSDL support the new screen, and programs that use them should work after recompilation.


==CPU==
====From v3.9 to v4.2====
*<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.
*Should work directly for most programs if they don't contain any OS-version specific addresses (SYSCALL_CUSTOM(), hooks, etc.)


==Hardware==
====From v3.6 to v3.9====
*<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;''
*Migration to newlib and libsyscalls. os.h and common.h shouldn't be used anymore. Use the standard C API directly.
*<tt>BOOL is_cm</tt>: since v3.1 r863. <tt>TRUE</tt> on TI-Nspire CM/CM-C.
*Introduction of the new [[Zehn]] format. Makefiles need to be updated to use [[Zehn#genzehn|genzehn]] and [[Zehn#make-prg|make-prg]].
*<tt>BOOL has_colors</tt>: since v3.1. <tt>TRUE</tt> if the device has a screen in color.
*<tt>BOOL is_touchpad</tt>: <tt>TRUE</tt> on a TI-Nspire Touchpad or on a 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*''.


==Time==
====From v2.0 to v3.1====
*<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.
*Programs must be rebuilt to work on TI-Nspire CX because of several hardware changes. Programs with low-level accesses to hardware must also be slightly adapted: some hardware controllers have changed and their registers are laid out differently. The [[libndls#Hardware|IO() macro]] can be used to select the address corresponding to the TI-Nspire model.
*<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.
**The LCD control register of the [[Memory-mapped_I/O_ports#C0000000_-_LCD_controller|LCD controller]] has moved from C000001C to C0000018. Use IO_LCD_CONTROL instead.
**The [[Memory-mapped_I/O_ports#900D0000_-_Second_timer|timer module]] has changed and has completely different registers
**Programs are run in color mode. Add ''clrscr(); lcd_ingray();'' at the beginning of a program ported from classic TI-Nspire to CX (the ''clrscr()'' avoids displaying color data that remains in screen buffer)
**Keep the TI-Nspire classic user base in mind: make your programs compatible with both color and grayscale mode with the help of ''has_color'' . The color screen buffer is in [[Memory-mapped_I/O_ports#A4000000_-_Internal_SRAM|R5G6B5 mode]].
*Programs which use ''show_msgbox()'' must be rebuilt with the new SDK, even for TI-NSpire classic
*SYSCALL_CUSTOM(): the first parameter should now only contain [[Ndless_features_and_limitations#Syscalls|OS v3.1 addresses]].


==Configuration==
====From v1.7 to v2.0====
*<tt>void cfg_register_fileext(const char *ext, const char *prgm)</tt>: (since v3.1 r797) associate for Ndless the file extension <tt>ext</tt> (without leading '.') to the program name <tt>prgm</tt>. Does nothing if the extension is already registered.
* Touchpad key map support: rebuild your programs with the SDK of v2.0, which includes an updated <tt>isKeyPressed()</tt> function. Make sure that the programs do not depend on keys specific to the Clickpad.


==Debugging==
====From v1.1.x to v1.7====
*<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.


==Deprecated==
C and assembly programs:
===Common types===
* The syscall convention has changed, programs built with Ndless < v1.7 need to be rebuilt without any change to the code. This format should be compatible with the new OS versions once supported by Ndless, as long as backward compatibility can be kept.
Deprecated. Use #include <stdbool.h> instead.
* Custom syscalls should be defined using SYSCALL_CUSTOM (see above)
<tt>typedef enum bool {FALSE = 0, TRUE = 1} BOOL;</tt>
* The "PRG\0" signature before main() isn't required anymore, you can remove it
* MakeTNS doesn't exist anymore. You must objcopy directly to the .tns file in your Makefile.
* The program format is not specific to an hardware model anymore. You can now build your programs only once without defining NSPIRE_HARDWARE.
* OS v1.1 is not supported anymore. Check that your programs still work on OS v1.7.
* The program path is passed to the main function by following the C calling convention instead of using register r9


===Old screen API===
Assembly programs:
The following section is only valid if using the OLD_SCREEN_API define.
* The way to call syscalls has changed: replace 'oscall <os_function>' with 'syscall(<os_function>)'


*<tt>SCREEN_BASE_ADDRESS</tt>: address of the screen buffer. Read from the LCD controller, caching it is recommended.
====From v1.0 to v1.1====
*<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
C and assembly programs:
*<tt>SCREEN_HEIGHT</tt>: screen height in pixels
* Install the toolchain as described above. Your project doesn't need to follow the Ndless file tree anymore.
*<tt>void clrscr(void)</tt>: clear the screen
* Adapt your Makefile based on src/arm/Makefile or src/arm/demo/Makefile
*<tt>BOOL lcd_isincolor(void)</tt>: since v3.1. Check the current LCD mode.
* You may upgrade to the latest version of YAGARTO. Don't forget to delete any remaining *.o file before rebuilding a project.
*<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.
Pure-assembly programs:
*<tt>volatile unsigned *IO_LCD_CONTROL</tt>: since v3.1. LCD control register of the LCD controller
* Make sure that the file extensions is in uppercase (.S)
* Add the "main" symbol as described in the previous section
* You do not need to define the symbol "_start" anymore

Revision as of 14:36, 21 June 2019

��Ndless combines a resident program and utilities to open the TI-Nspire to third-party C and assembly development. Ndless is distributed under the Open Source Mozilla Public License.

The installation of Ndless on a TI-Nspire is required to be able to run assembly programs.

Find help for any Ndless related question or issues on the issue tracker.

Latest stable release

Developing with Ndless

Tutorials and general information are available in the Development resources section.

Version upgrade

The executable format, the conventions and the header files are currently being defined and prone to change. Some changes are forced by This section describes the upgrade steps between the different releases of Ndless.

To v4.4 r2005

  • Should work directly for most programs if they don't contain any OS-version specific addresses (SYSCALL_CUSTOM(), hooks, etc.)

To v4.2 r2004

  • HW rev. W introduced a new 240x320px screen which breaks most Ndless programs.
  • A new API to make use of the different screen is now available, SCREEN_BASE_ADDRESS is only available in OLD_SCREEN_API (Add the define to the compile options) mode. See LCD API for information about the new API.
  • Nspire I/O and nSDL support the new screen, and programs that use them should work after recompilation.

From v3.9 to v4.2

  • Should work directly for most programs if they don't contain any OS-version specific addresses (SYSCALL_CUSTOM(), hooks, etc.)

From v3.6 to v3.9

  • Migration to newlib and libsyscalls. os.h and common.h shouldn't be used anymore. Use the standard C API directly.
  • Introduction of the new Zehn format. Makefiles need to be updated to use genzehn and make-prg.

From v2.0 to v3.1

  • Programs must be rebuilt to work on TI-Nspire CX because of several hardware changes. Programs with low-level accesses to hardware must also be slightly adapted: some hardware controllers have changed and their registers are laid out differently. The IO() macro can be used to select the address corresponding to the TI-Nspire model.
    • The LCD control register of the LCD controller has moved from C000001C to C0000018. Use IO_LCD_CONTROL instead.
    • The timer module has changed and has completely different registers
    • Programs are run in color mode. Add clrscr(); lcd_ingray(); at the beginning of a program ported from classic TI-Nspire to CX (the clrscr() avoids displaying color data that remains in screen buffer)
    • Keep the TI-Nspire classic user base in mind: make your programs compatible with both color and grayscale mode with the help of has_color . The color screen buffer is in R5G6B5 mode.
  • Programs which use show_msgbox() must be rebuilt with the new SDK, even for TI-NSpire classic
  • SYSCALL_CUSTOM(): the first parameter should now only contain OS v3.1 addresses.

From v1.7 to v2.0

  • Touchpad key map support: rebuild your programs with the SDK of v2.0, which includes an updated isKeyPressed() function. Make sure that the programs do not depend on keys specific to the Clickpad.

From v1.1.x to v1.7

C and assembly programs:

  • The syscall convention has changed, programs built with Ndless < v1.7 need to be rebuilt without any change to the code. This format should be compatible with the new OS versions once supported by Ndless, as long as backward compatibility can be kept.
  • Custom syscalls should be defined using SYSCALL_CUSTOM (see above)
  • The "PRG\0" signature before main() isn't required anymore, you can remove it
  • MakeTNS doesn't exist anymore. You must objcopy directly to the .tns file in your Makefile.
  • The program format is not specific to an hardware model anymore. You can now build your programs only once without defining NSPIRE_HARDWARE.
  • OS v1.1 is not supported anymore. Check that your programs still work on OS v1.7.
  • The program path is passed to the main function by following the C calling convention instead of using register r9

Assembly programs:

  • The way to call syscalls has changed: replace 'oscall <os_function>' with 'syscall(<os_function>)'

From v1.0 to v1.1

C and assembly programs:

  • Install the toolchain as described above. Your project doesn't need to follow the Ndless file tree anymore.
  • Adapt your Makefile based on src/arm/Makefile or src/arm/demo/Makefile
  • You may upgrade to the latest version of YAGARTO. Don't forget to delete any remaining *.o file before rebuilding a project.

Pure-assembly programs:

  • Make sure that the file extensions is in uppercase (.S)
  • Add the "main" symbol as described in the previous section
  • You do not need to define the symbol "_start" anymore
Retrieved from "https://hackspire.org//index.php?title=Libndls&oldid=1698"