Ndless features and limitations

From Hackspire
Revision as of 23:39, 9 August 2013 by ExtendeD (talk | contribs) (typo)
Jump to navigation Jump to search

Ndless combines an executable loader and utilities to open the TI-Nspire to third-party C and assembly development.

This article covers advanced features of Ndless for developers. If you want to try C and assembly development on the TI-Nspire, start with the tutorial.

nspire-tools utility

Since v3.1 r541, nspire-tools can be used to execute various actions on your build environment.

  • nspire-tools new <program>: create in the current directory a Makefile to build a program called <program>.tns

Entry point

You can optionally define the standard argc and argv parameters in your main function definition to get the current program path in argv[0]: 

int main(int argc, char *argv[]) {
  printf("Run from '%s'\n", argv[0]);
}

bFLT loader

bFLT is simple and lightweight executable format commonly used by embedded Linux distributions, and supported since Ndless v3.1 r806 (thanks tangrs). It is now the default binary format when building an Ndless program with the SDK. The nspire-ld-bflt linker is used to build to the bFLT format.

Ndless original loader: Global variables and initialization

This section applies when using the original (now deprecated) program format and loader. The nspire-ld linker is used to build to this format.

Global variables are generally defined in the BSS section of the executable format.

BSS sections are currently not allocated dynamically by the program loader of Ndless: global variables will make your programs bigger so use them with care, switch to malloc() when necessary.

Global variables with initialization data, or variables with constant initializers which requires relocation (for example an array of function pointers, or a structure containing static strings) must be relocated manually with the non standard nl_relocdata() because of the limited features of the lightweight program loader. 

int global_int;
int* global_array[] = {&global_int};
nl_relocdata((unsigned*)global_array, sizeof(global_array)/sizeof(global_array[0]));
printf("global_int=%i\n", *global_array[0]);

Using static libraries

Since v3.1 r604, Ndless's nspire-gcc and nspire-ld compilation tools create and use the directory .ndless for static libraries. This directory is stored in ${USERPROFILE}, which should be something like C:\Users\<Your Account> on Windows. This is the recommended directory to drop the third-party library artifacts your program uses, as it is untouched during Ndless SDK version upgrades.

To use a static library:

  • Drop the include file (.h) into .ndless/include
  • Drop the library file (lib*.a) into .ndless/lib
  • In your program's Makefile, Add to LDFLAGS the option -l<libname>, where libname is the name of the library without its lib prefix (for example for libnspireio2.a it should be -lnspireio2)

Checking Ndless's version

Ndless is frequently updated with new syscalls. Calling a syscall on a previous version of Ndless will make the calculator crash.

Protect your Ndless version-dependent program with libndls's function assert_ndless_rev(unsigned required_rev) at the beginning of it. The revision is the ZZZ part of "vX.Y rZZZ". libndls functions and syscalls which won't work if Ndless is not up-to-date have the revision indicated in their documentation.

Syscalls

Syscalls are OS functions exposed by Ndless to C and assembly programs. Some syscalls are part of standard libraries and may be used to port programs to the TI-Nspire more easily.

To call a syscall in assembly, use syscall(<symbol name>).

If you have found an interesting syscall not defined in the latest version of Ndless, you can temporary define it locally to your program with SYSCALL_CUSTOM(). For example to call the syscall int internal_func(char *s) you have found, define in one of your program's header files: 

static const unsigned internal_func_addrs[] = {0x10123456, 0x10654321, 0x10234567, 0x11234567, 0x11234567, 0x11234567}; // non-CAS 3.1, CAS 3.1, non-CAS CX 3.1, CAS CX 3.1, CM-C 3.1, CAS CM-C 3.1 addresses
#define internal_func SYSCALL_CUSTOM(internal_func_addrs, int, char *s)

This is a temporary workaround which will force a re-build of the program each time a new OS version supported by Ndless comes out. You should suggest the syscall to the Ndless development team to make it standard, publicly available and maintained.

Functions alternatives

Some standard functions cannot or aren't yet provided by Ndless. Here are possible alternatives for these functions.

OS variables

Ndless also abstracts access to some OS variables.

To read from or write to these variables in assembly, use osvar(<symbol name>). The address of the variable is returned in r0.

Assembly source code

Pure-assembly programs must define the global symbol "main" as their entry point. See src/samples/hella/hella.S.

Always make sure that the assembly files extensions are in uppercase (.S) to let them be preprocessed by the C preprocessor on which Ndless include files depend.

Thumb state

The TI-Nspire ARM9 processor features a Thumb instruction set state which improves compiled code density with 16-bit instructions instead of 32-bit.

Only ARM state main() entry points is currently supported, but other source files may be built in Thumb state. Switching from one state to the other is transparent to C programs as long as the -mthumb-interwork GCC switch is used. To build a .c file in Thumb state, use a GCC command similar to: 

test_thumb.o: test_thumb.c
 $(GCC) $(GCCFLAGS) --mthumb-interwork -mthumb -c $< -o $@

Calling syscalls in thumb state is supported by Ndless.

Assembly source files must declare the instruction set to use with the .arm and .thumb directives (ARM is the default). Switching from one mode to the other requires specific tricks.

Newlib

Newlib is an implementation of the C library intended for use on embedded systems, installed with the YAGARTO GNU ARM Toolchain.

Compatibility of Ndless with Newlib has not been tested. You may get definition conflicts and crashes due to Newlib running without the required relocation that Ndless doesn't provide. You should always build your programs with the nspire-ld flag -nostdlib, except if you need the single precision floating-point helper functions internally called by GCC when required (__aeabi_fadd, ...).

File association

File association is configured through the configuration file ndless.cfg.tns (see the User Guide). Once the file extensions supported by your program are declared in the file, your program is run with the argv[1] parameter set to the full path of the file open from the OS document browser. Check that argc >= 2 to know if the program is being run through file association. Always check the format of file open this way.

You may ask Ndless's maintainers to add your file assocation to the default ndless.cfg.tns file, if the extensions aren't already defined.

Resident programs

You can ask Ndless not to free the program's memory block after it exits by calling void nl_set_resident(void). This can be use for resident programs such as OS patches.

Resident programs shouldn't use argv[] after returning.

This is currently no way to free a resident program memory block.

Builtin functions

Ndless exposes internal features and states throw the nl_*() functions.

  • BOOL nl_isstartup(void): (since v3.1 r540) returns TRUE if the program is currently being run at OS startup. See the User Guide.
  • int nl_osvalue(const int values[], unsigned size): returns the value of values corresponding to the OS version. size is the number of values. values[0] corresponds to non-CAS 3.1, values[1] to CAS 3.1, values[2] to non-CAS CX 3.1, values[3] to CAS CX 3.1, values[4] to CM-C 3.1, values[5] to CAS CM-C 3.1.
  • void nl_relocdata(unsigned *dataptr, unsigned num): see Global variables
  • void nl_set_resident(void): (since v3.1 r553) see Resident programs
  • void nl_no_scr_redraw(void): (since v3.1 r756) don't restore the screen on program exit
  • BOOL nl_loaded_by_3rd_party_loader(void): (since v3.1 r791) return TRUE if a third-party Launcher was used to boot the OS, such as nLaunch/nLaunchy
  • int nl_exec(const char *prgm_path, int argsn, char *args[]): (since v3.1 r875) run a program. prgm_path is its full path with .tns extension, argsn is args[] size, args[] sets the program additional arguments, passed through the main function's argv[] parameter. args[] must not include the program name (argv[0]) nor the terminating NULL argument. If the the program is run through a file association, argv[2] will be set to args[0]. argsn and args[] may be respectively 0 and NULL.
Retrieved from "https://hackspire.org//index.php?title=Ndless_features_and_limitations&oldid=1493"