Easy C++ Manual

Easy C++ Manual

The library facility

The library facility in C is used for the creation and maintenance of libraries. It allows you to build your own libraries of functions for special applications. These may be used instead of, or in addition to, the libraries provided with the package. The Library facility allows you to to create new libraries, and insert you own objects files into them. Object files inserted into libraries are called modules , and may contain one or more functions. You may insert, delete or extract modules from libraries, but you cannot do the same for the individual functions within the modules.

The general form of the library command is:

*library [filename] [qualifiers]

If the filename is omitted, the default library specified by the system variable Lib$Library is used. By default it is the shared library STDCLib . The library pathname is specified by the system variable Link$Library and is set to !EasyC.Libraries . A full list of qualifiers can be displayed by typing:

*help library

Quali fier -create

Abbreviation -c

This qualifier allows a new library to be created.

*library NewLib -create

This command creates a new library containing no functions.

Quali fier -verify

Abbreviation -v

This qualifier verifies the integrity of a library. In addition it displays information about the library, including its date of creation, copyright and identification messages.

*library NewLib -verify

or for the default library

*library -verify

Quali fier -list

Abbreviation -l

The -list qualifier lists the contents of a library. For example, to list the contents of the default library, type:

*library -list

Or, to list the contents of the ROSLib library, type:

*library ROSLib -list

Each function in the library is listed, together with the object module in which it is contained.

Quali fier -history

Abbreviation -h

This qualifier controls the library history mechanism. To turn this on, use:

*library ROSLib -history=on

To turn the history mechanism off, use:

*library ROSLib -history=off

To display the history of a library, use:

*library ROSLib -history

Quali fier -insert

Abbreviation -i

The -insert qualifier allows you to add an object module to a library. The module should be in object format (AOF) e.g. generated by the C compiler, another compiler or an assembler. For example, to add the object file o.utils to the NewLib library ensure that you are in the parent directory of the o directory and type:

*library NewLib -insert=utils

A number of modules may be added as follows:

*library NewLib -insert=utils,utils1,utils2

Quali fier -delete

Abbreviation -d

The -delete qualifier allows you to delete an object module from a library. For example, to delete utils module from NewLib type:

*library NewLib -delete=utils

Please note that you cannot delete individual functions, only complete modules.

Quali fier -extract

Abbreviation -e

The -extract qualifier extracts an object module from a library and places it on disc. The module is not deleted from the library. Use � extract to copy object modules from one library to another. For example to extract the utils module from the NewLib library type:

*library NewLib -extract=utils

The module will be placed in the current directory.

Quali fier -copyright

Abbreviation -co

This qualifier allows a copyright message to be specified for a library, and is displayed whenever the library is listed or verified. It can only be used when a library is created, and cannot be changed afterwards. For example:

Please note that the copyright string must be enclosed in quotes if it contains spaces.

Quali fier -identification

Abbreviation -id

The -identification qualifier allows an identification string to be specified for a library. This string is displayed when the library is listed or verified. The identification qualifier can only be used at the time the library is created, for example:

*library NewLib -create -identification="Version 1.00"

F iles compiled using Easy C may contain assembly language in the form of ARM mnemonics and floating point instructions. A piece of assembly language may appear at any point that a function definition may appear in a C program. It is enclosed in the pre-processor lines:

#pragma asm ... #pragma endasm

The instruction format is identical to that normally recognised for the ARM. The code is parsed on a line-by-line basis. If more than one instruction is placed on a line, they must be separated by colon characters. The assembler is pre-processed just as a normal C program, so the assembly language programmer may take advantage of the powerful conditional and macro processing capabilities of the C pre-processor. The code produced is in AOF (Acorn Object File) format.

Registers

Normal register names may use the format: R0 or a1 etc. The second form is that used in the ARM procedure calling standard. The floating point register names may use: F1 or f1, etc. The stack pointer may be: R13, sp or SP. The link register may be: R14, lk or link. The program counter may be: R15, pc or PC.

The procedure call standard names and normal names may be used at will. It is suggested that the procedure call standard name format be used when an external procedure call is made.

Expressions

Where a constant is required in assembly language, a constant expression may be used. The operators which may be included in the expression are normal C constant expressions. Hex numbers are represented by the characters 0x followed by the number, octal numbers by 0 followed by the number. Character constants are enclosed in single quotes. If an immediate value is required and is not loadable in one instruction, an error is given.

Labels

A label is declared by prefixing its name by a full stop. A label declared in this way is not visible outside of the file being compiled. To make it external it must be exported by the EXPORT keyword. This may appear either before or after the definition of the label.

.label1 .label2 EXPORT label2

In the above example label2 is exported and may be referenced outside of the file. Any label may be used in a C program as a function. If the label is exported, it may be used in a C program which is linked to the file. A local label may be declared as follows:

.123$

This label is only in scope in assembly language, and may not be used in C. All the normal instructions may use labels ( ADR , LDR etc.), and labels may be targets for branch instructions.

Comments

A comment can be included at any point by prefixing it with a semicolon. Comments always terminate at the end of lines. In addition, C style comments may also be used i.e. the comment is enclosed in /* and */ pairs.

Pseudo instructions

IMPORT <label> import a symbol from another file EXPORT <label> make a symbol visible outside this file ALIGN align to a 4 byte boundary DCB <expr[,expr...]> declare bytes (may be in quotes) DCD <expr[.expr...]> declare words ADR <reg>,<label> address of LDR <reg>,<label> load at address STR <reg>,<label> store at address LDF <reg>,<label> load floating at address STF <reg>,<label> store floating at address

The following instructions are pseudonyms for DCB and DCD:

DEFB, EQUB DCB DEFW, EQUW DCD

Note: all code and data written using the assembler is placed in the C$$Code area of the object file and is therefore notionally read-only. If it is desired to declare writable data, it must be done outside the assembler by use of normal C variable definitions.

Software interrupts

The ARM SWI instruction allows the programmer to enter ARM supervisor mode and perform some complex operation under a "software interrupt". This assembler recognises all the SWIs that are present in the operating system (including extension modules). There is no need to define symbols to represent SWIs, they can be invoked by simply quoting their name in the SWI instruction.

For example:

SWI OS_WriteS SWI Wimp_GetRectangle SWI OS_WriteS+'A' SWI 0x12344

Macros

The assembly language is pre-processed by the C pre-processor. This allows macros to be defined using the #define pre-processor control line. This is of the form:

#define <macro-name>[(parameters)] <replacement text>

A macro may take parameters. If it does, these are textually substituted into the line before any lexical analysis is performed. Instructions may be separated on one line by colons. This feature may be taken advantage of, to produce multi-line macros. Conditional assembly may also be performed by using the C pre-processors #if , #ifdef etc. control lines.

Errors

Syntactic and semantic errors are reported as the normal errors given by the C compiler.

Example program

The following program Asm_ex demonstrates the use of assembler in a C program. It is supplied within the programs directory of the CD-ROM.

#pragma asm

/* this is the assembly language equivalent of the ubiquitous

   "hello world" program. It prints "Hello World" a number of 

   times followed by a number. */

        IMPORT printf             ; imported from run time library

.string                           ; declare a label string

        DCB "Hello World %d\n",0  ; declare some bytes

        ALIGN                     ; align to word

.limit                            ; declare a label (not visible      
            
  ; outside)

        DCD 10                    ; declare a word 10

        EXPORT example            ; label example is to be exported

.example                          ; declare the label

        STMFD SP!,   ; store regs

        MOV R4,#0                 ; set counter to 0

        LDR R5,limit              ; load limit

.1$                               ; declare a local label 1$

        ADR a1,string             ; get address of string into first arg

        MOV a2,R4                 ; get counter into second arg

        BL printf                 ; call printf

        ADD R4,R4,#1              ; add 1 to counter

        CMP R4,R5                 ; at limit?

        BNE 1$                    ; no, do another

        LDMFD SP!,^    ; return

#pragma endasm

main()

T he Easy C compiler supports 3 simple extensions to the standard ANSI specification. These extensions may only be used if the compiler is switched to Extended mode using the Standard option on the Setup dialogue box, or using the -standard qualifier from the command line.

1. The symbol $ is allowed in variable names.

2. Binary numbers can be specified by prefixing them with 0b .

3. Easy C supports automatic argument counting for use when writing functions in ARM assembler where you need to know how many arguments are being passed to the function. This facility is used by inserting the keyword auto in the function declaration as follows:

  
function(auto int data, ...);

The number of arguments is stored in the top 6 bits of register a1 , with the first argument in register a2 .

Something to bear in mind

While every care has been taken the publishers cannot accept responsibility for any errors in page numbering, index links and so on. We're working with a 50,000 word document which does make being 100% accurate difficult.

We may, however, have found a proof reader this time before this manual goes to press. If this text is still here, and you wish to volunteer, please call APDL on 0208 778 2659: your assistance would be most useful!

APDL and ProAction