Charm Tools
- !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 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 Logging option shows a sub-menu containing logging options:-
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 100K.
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 (up to 60) 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)
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), and the Asm file requests the compiler to generate an ARM assembler source file (usually not set):
The options for running the compiler from the command line are :-
*armc <source file> [-asm <assembler file>] [-obj <object file>]
[-list <list file>]
[-global] [-debug] [-noobj] [-throwback]
The -asm switch produces an ARM assembler output file which is stored in the arm project sub-directory unless a fully qualified filename is provided (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 which is stored in the lst project sub-directory unless a fully qualified filename is provided (by default no assembler list file is produced).
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 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.
Assembler
In the shell menu, the Assembler Object code option generates object code from the assembly source code (usually set), and the List file option generates an optional list file containing detailed assembly information (usually not 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:$.myproject
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> [-object <object list>] [-nolink]
[-program <program file>] [-map <map file>]
[-relocatable]
[-base <swi base>] [-code <Kb>] [-data <Kb>]
[-stack <bytes>]
The object files can be specified on the command line and are separated by spaces. Alternatively, the -object allows a file containing the names of the object files (one per line) to be specified.
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 -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 (default 10,000).
e.g. *arml myproject startup rtl -map mapfile
Here is the map file for the myproject template in the charm user area:
ARM Linker map file for application myproject
Object -> myproject
Code = 00000000 Data = 00000000 Address = 00000000
Object -> main
Code = 00000038 Data = 0000000C Address = 00000034
Object -> rtl
Code = 00000054 Data = 00000070 Address = 00000034
Object -> startup
Code = 00002868 Data = 00000094 Address = 00000544
Image code size = 00002BB4
Image direct data size = 000000C0
Image address data size = 0000055C
Code table
Main~start : 00008084 MyProject~start : 0000804C
Rtl~_rtl_program_start : 0000A73C Rtl~exit : 00008584
Rtl~hash : 00008550 Rtl~jump_label : 00008544
Rtl~set_label : 00008538 link_application : 0000A8B4
link_entry : 0000AAE4 link_init : 0000A934
link_start : 0000AAC0 ~~t_divide : 0000AB40
~~t_modulo : 0000AB24
Data table
#58454241 : 0000AC0C #C39B00 : 0000AC04
#FFF : 0000AC08 Rtl~Convert : 0000B1C4
Rtl~Dir : 0000B198 Rtl~Error : 0000B1E0
Rtl~File : 0000B180 Rtl~Heap : 0000B1A4
Rtl~In : 0000B11C Rtl~Memory : 0000B1B4
Rtl~Out : 0000B13C Rtl~Parse : 0000B1F0
Rtl~Str : 0000B0F8 link_command : 0000AC98
link_extension : 0000AC58 link_help : 0000AC5C
link_stack : 0000AC28 link_title : 0000AC6C
module_base : 0000AC10
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 F1. Press 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
A useful search tool written in Charm. Try:
*$.charm.system.lnk.search $.charm.system.src * proc
for example search output:
New Project
Create new buildable Charm skeleton projects using drag and drop with this 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.
