Charm Tools


The Charm tools described in this section are :-

  •      !Charm          Charm shell
  •      armc              Compiler
  •      arma              Assembler
  •      arml              Linker
  •      edit              Editor

Charm Shell


The Charm shell supports a menu system which allows a number of options to be set for the Charm utilities with each tool having its own sub-menu for setting options :-

The Quit option closes the shell.

The Save choices option saves the current shell settings in text file ShellOptions in the current Charm <Obey$Dir> application directory.

The Target VFP option causes the compiler and linker to generate code which uses the VFP co-processor of the ARM CPU.

The Logging option shows a sub-menu containing logging options:-

The Charm Log contains the results of commands processed by drag and drop operations to compile, assemble and link Charm programs including details of the current folder context, whether each command was successful, and an elapsed time measurement to 10ms precision:-

In case of a compilation error you can expect to see an additional error window similar to the following with error details (the Throwback option was not enabled in this example):- 


Pressing the Edit button will cause the Charm editor to be invoked at the error location so that the error can be corrected. The error window will automatically close following a subsequent successful compilation of the file.

It is possible to switch off display of the Charm log, and to control the maximum number of lines displayed. Note that setting the size to too large a value may cause the shell to run out of memory unless the size of its Wimp slot is increased from the default value of 150K.

The Errors control option shows a sub-menu containing error handling options:-


It is possible to stop shell processing on occurrence of the first error to avoid multiple error boxes and to request throwback processing.

The Throwback option includes a Throwback button in error windows which allows an external editor that supports throwback (e.g. !StrongEd) to be invoked at the line of a compilation failure. Please note you must have arranged for the DDEUtils module to have been loaded for this option to work. 

The Info option shows a sub-menu containing Charm information :-  

Files or groups of files (same directory only) may be compiled by dragging them on to the Charm icon.

Text files may be edited by holding down the shift key for the duration of the drag operation. The files may be selected from either inside a directory, or from desktop shortcuts which may have been sourced from different directories. Please ensure sufficient task memory has been pre-allocated for larger edits or the heap will become exhausted.

'build files  may also be run by dragging them on to the Charm icon. The allowed commands within a 'build file are:

  • # remark - comment
  • log message - log a message to the Charm shell log (one per script)
  • dir folder - process a sub-directory
  • module name - compile a module (if local i.e. unqualified) and link it into any program 
  • program filename - generate a program (one per script)
  • map filename - generate a program map file (one per script)
  • relocatable - generate a module instead of an application
  • stack size - specify the stack size in bytes for a program (default is normally sufficient)
  • code size - specify maximum code size in Kb (default is normally sufficient)
  • data size - specify maximum data size in Kb (default is normally sufficient)

Be aware that modules are compiled in the reverse order to which they appear in the build file, and cannot contain cyclic dependencies. All imported modules must be compiled before the importing module can be compiled, so for instance the build scripts build the libraries first, then the tools and finally the demos.

Note that configuration options set in the Charm shell can also be set as command line parameters when the utilities are run from the command line prompt. The location of the utilities are set using aliases so that they are available whatever the current directory is set to.

Compiler


In the shell the Object file option request the compiler to generate an object file (usually set):

The options for running the compiler from the command line are :-

*armc <source file> [-asm <assembler file>] [-obj <object file>]
                    [-list <list file>] [-vfp]
                    [-global] [-debug] [-noobj] [-throwback]

The -asm switch produces an ARM assembler output file (by default no assembler file is produced).

The -
obj switch allows an alternative object file location to be specified (by default the object file has the same name as the source file and is stored in the obj project sub-directory).

The -list switch produces an ARM assembler list output file (by default no assembler list file is produced).

The -vfp switch compiles the module to use the ARM VFP coprocessor for floating point operations.

The -global switch makes all procedures global so that they appear in the linker map file.

The 
-debug switch includes debug comments if an assembler source or list file is specified.

The
-noobj switch allows generation of an object file to be suppressed.

The
-throwback switch requests the compiler to generate error throwback information for the Charm shell. The shell can use this to pass details of a compilation error to the editor which then opens with the cause and location of the error. If this switch is not supplied, compilation error information is output to the screen.

 e.g.     *armc myproject -list $.myprjlst -debug

Assembler


In the shell menu, the Assembler Object code option generates object code from the assembly source code (usually set): 

The options for running the assembler from the command line are :-

*arma <source file> [-list <list file>] [-noobj] [-obj <object file>]

The -list switch allows a list file to be specified if required, otherwise it is not generated.

The 
-noobj switch disables object file generation.

The 
-obj switch allows any object filename to be chosen, otherwise the output file defaults to the same filename as the source file in the appropriate obj directory.

e.g.
*arma myproject -obj ram:$.myprjobj

Linker

In the shell menu the Linker Module option generates a module instead of an application (usually not set):

The options for running the linker from the command line are :-

*arml <object files> [-nolink]
                     [-program <program file>] [-map <map file>]
                     [-relocatable] [-vfp]
                     [-base <swi base>] [-code <Kb>] [-data <Kb>]
                     [-stack <bytes>]

Usually the linker uses the contents of the project 'build file in the current directory to specify which modules are linked into what program along with other linker options. Note that any implicitly referenced modules that are required but not explicitly listed are automatically included.

Additional object files can be specified on the command line and are separated by spaces.


The -nolink switch disables generation of an application or module file.

The
 -program switch allows any program filename to be chosen. If not path is present the file is created in the project directory.

The 
-map switch generates a map file containing code and data address information.

The -relocatable switch generates a module rather than an application (ensure either the default or a custom module file is included in the 'build file).

The -vfp switch requests that the program uses the ARM VFP coprocessor for floating point operations.

The  -base defines the base software interrupt number the module responds to if it contains swi handling code. 

The 
-code switch specifies the maximum code size that can be linked in Kb (default 80).

The 
-data switch specifies the maximum data size that can be linked in Kb (default 30).

The -stack switch specifies the size of the program stack in bytes (default 10,000).

e.g. with MyProject as the current directory:     *arml -map $.myprjmap

Here is part of the map file for the myproject template in the charm user area:

        ARM Linker map file for application myproject
-> hostfs:$.charm.lib.obj.rtl
   Code = 00000000 Data = 00000000 Address = 00000000 [00008054]
-> hostfs:$.charm.lib.obj.error
   Code = 000006D8 Data = 0000001C Address = 00000048 [0000872C]
-> hostfs:$.charm.lib.obj.program
   Code = 00000814 Data = 00000024 Address = 00000048 [00008868]
-> hostfs:$.charm.lib.obj.string
   Code = 000010F0 Data = 00000068 Address = 0000007C [00009144]
-> hostfs:$.charm.lib.obj.fp
   Code = 000020CC Data = 00000074 Address = 0000011C [0000A120]
-> hostfs:$.myproject.obj.myproject
   Code = 000025F0 Data = 0000007C Address = 0000011C [0000A644]
-> hostfs:$.charm.lib.obj.out
   Code = 0000269C Data = 00000088 Address = 000001A4 [0000A6F0]
-> hostfs:$.myproject.obj.main
   Code = 000034B0 Data = 00000094 Address = 0000026C [0000B504]
Image         code size = 000034CC
Image direct  data size = 000000AC
Image address data size = 0000028C

You can link directly into the !RunImage file of an application directory, or group programs into a ~bin directory where this is convenient. If no path is specified, the program is placed directly in the project directory.

Editor 

When starting out with the editor, the most important key is the Help key F1Press it to see all available commands:

The Auto indent option supports automatic indentation at the same level as the previous line when entering Charm source code.

The New file sub-menu allows a filename to be entered when a new file is to be created.

The Display mode sub-menu allows a display mode to be selected which the editor will run in (mode 32 recommended).

The X, Y indents sub-menu allows horizontal and vertical pixel offsets to be set for the text which appears in the edit windows.

The Colours sub-menu allows the logical screen colours of the background and foreground text to be specified, and the logical colours of selected blocks of text. 

e.g.     *edit test test1 test2

 Charm Utilities

The Charm utilities described in this section are :-

  •      search           Search
  •      !NewProject Create new project
  •      !SciCalc       Scientific calculator

Search

A useful search tool written in Charm. Try:

*<Charm$AppsDir>.search $.charm.system.src * proc

for example search output:

!NewProject

Quickly create new buildable Charm skeleton projects using drag and drop with the !NewProject application, then tailor them to your project's needs:

!SciCalc

A handy calculator with a few common and handy scientific operations to illustrate real number processing in Charm:

Make a Free Website with Yola.