
TO WORD WRAP THIS TEXT:

Click Edit on this screen's above toolbar and then click on Word Wrap.

TK3 ASSEMBLY NOTES - UPDATED 23FEB07

Some of this information updates that given in the published EPE TK3 text.

Always check the Updates file for any information that affects these notes. It is normally issued whenever an update to TK3 is released and is accessible via the "Latest Updates" button at the bottom of the main TK3 screen.

The Toolkit TK3 Assembly routine recognises TASM and MPASM source code commands, a list of which can be viewed by clicking the Commands button on the main screen. It produces MPASM HEX (hexadecimal) files which can be sent to the PIC through the Programming button option Send HEX.

It is a conscious decision not to create TASM OBJ files via the Assembly option. MPASM HEX files are the "industry standard" and the author wishes to "wean" you from OBJ files.

When the Assembly routine has been run without error, the details given in the Programming panel are updated accordingly, allowing you to then commence programming by clicking the Send button that appears on the Assembly screen. It is the HEX file that is sent.

Note that lengthy file names may sometimes not be seen in their entirity. However, they are displayed "actively" in that you can click on them and then use the cursor keys to reveal the hidden parts as well. This may be done for any changeable file name on the main screen and on some others. The names cannot be changed on screen - other file names can only be selected via the Directory (DIR) option buttons.

It is only the file names themselves that are displayed. If you want to know their full path names as well, double-click on the file name and a message box will show you the full details (this applies to any on-screen file name).

SOURCE CODE COMMANDS

In your source code (ASM) you can only include PIC commands that are quoted in the Commands screen (the full set of "conventional" commands, plus a few "shorthand" commands with which some MPASM users may be familiar).

Since June 04 TK3 accepts Configuration data when embedded in the ASM file in the form of (for example):

    __CONFIG        _PWRTE_ON & _WDT_OFF & _HS_OSC 

and 

    __CONFIG H'3FF1'

The statement may be in upper or lower case. Note that two underscores ("_") precede the word CONFIG. This second example command automatically sets the PIC16F84 configuration for CP OFF, POR ON, WDT OFF, XT oscillator when the HEX code is sent to it. Other hex code values can be found by examining the data produced through TK3's Config screen.

When such Config data is encountered in HEX files it is automatically routed to the PIC's Config memory at H'2007'.

Since the introduction of V1.3, TK3 can now handle Data Statements embodied in the source code as strings of values separated by commas, as in the following examples, all prefixed by DE following the ORG H'2100' statement (EEPROM address start). All the usual numerical formats are permitted, and the data is placed at consecutive addresses commencing from the ORG value stated. The range is from H'2100' to the maximum that the PIC permits.

	ORG H'2100'
	DE 10, 9, 8 ,7 ,6 ,5, 4, 3, 2, 1, 0
	DE 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
        DE $A, $B, $C, $FF
	DE H'A', H'B', H'C', H'FF'
        DE 'A', 'B', 'c'
        DE %00000001, %00000011
        DE B'00000001', B'00000011'
	DE HIGH 12345, LOW 12345

Note that the $ (dollar) and % (percentage) symbols are TASM symbols and are treated in the same way as the MPASM H' and B' prefixes respectively.

If an ORG address value between H'2000' and H'2008' is found, an intercept message appears and the assembly process ends. Code associated with such values must be removed and that required must be sent to the PIC as a separate process through the PIC Configuration screen. These are the locations uses:

H'2000' - H'2003' ID
H'2004' - H'2006' Reserved by Microchip
H'2007'           Config value
H'2008'           Reserved by Microchip

The ORG addresses given will be double these values, i.e H'2000' will be H'4000' (or the equivalent in decimal).

Any statement commencing with the word DATA (e.g. DATA XX - where XX can be a value expressed in binary, decimal or hex) is sent to the PIC as a RETLW XX command.

Since version V.4 TK3 recognises MPASM's HIGH and LOW commands.

DIRECTIVE "LIST P ="

TK3 recognises the LIST P = PIC16F84 type of structure in which the PIC type is stated (as recgnised by MPASM). Since TK3 V1.35, if the PIC type is found via such a directive, TK3 checks this against its own allocation of PIC type and updates its records accordingly if a match is found. If a match is not found TK3's records retain the existing PIC type and data is processed accordingly. (Note that you may add your own PIC type data via the Config screen.)

ERR AND LST BUTTONS

When assembling the source code, TK3 generates an Errors file (TKTEMP.ERR) and a List file (TK3TEMP.LST), both of which are held in the same folder that TK3 itself is held.

Any assembly errors found are recorded in the ERR file and repeated in the LST file.

The LST file records details of code values (in hex and binary) produced during assembly, along with the PIC addresses (Program Count, in both decimal and hex) at which they will be placed. Each List line is also numbered, in decimal. Also given are names of any files called in as INCLUDE files (see below). A separate line count value is given in respect of each file.

The original ASM source code text is stated alongside each code line, together with information on any code expansions that are made if use is made of "definitions" and certain MPASM "shorthand" commands (the options as stated when the Commands button is clicked).

Following the source and assembled code listing, details of the values for labels, equates and definitions, plus a repeat of error details, are included at the end. These show the names of any Include files as well.

Any errors found are shown on screen immediately on completion of assembly, as a Quick View window in which the errors are sorted in alphabetical order.

The ERR and LST files can be examined separately via the ERR and LST buttons in the Assembly window. The ERR file shows the errors in order of occurrence while assembling.

Note that the ERR and LST buttons are disabled when a new file for assembly is chosen via the directory (DIR button). They are re-activated at the end of assembly.

PIC ADDRESS LOCATIONS 0 to 3

Traditionally, since the format established by the original EPE Simple PIC Programmer of 1996, TASM OBJ files have ignored PIC address locations 0 to 3, the first ORG command (ORG 4) being the pointer at location 4 (Interrupt Vector), followed by ORG 5, pointing to the Program Start at location 5. This used to complicate the conversion of files between the TASM and MPASM dialects since MPASM files can include data for locations 0 to 3. It was previously necessary for users to manually correct converted files to adjust for this difference.

With Toolkit TK3, an attempt has been made to get round this problem and to allow either TASM or MPASM source code files to be assembled, automatically adjusting the composition of the HEX file accordingly.

However, to maintain compatibility with earlier TASM programmers and source code, TASM ASM files can continue to be assembled with data for locations 0 to 3 omitted (but this is discouraged). This data is automatically added to assembled HEX files if an ORG location greater than 3 is the first ORG statement found, so that the HEX code can also be sent via a true MPASM programmer.

The commands added are:

Location 0  GOTO 5 (code 10245 decimal, H'0528' hex)
Location 1  NOP    (code 0 decimal, H'0000' hex)
Location 2  NOP    (code 0 decimal, H'0000' hex)
Location 3  NOP    (code 0 decimal, H'0000' hex)

Users who have no interest in maintaining backward compatibility with the original TASM format can use all PIC locations as they wish, and in accordance with the needs of the PIC in question.

Note the following for PIC16x8x, PIC16F87x and PIC16F62x devices:

Command location 0 = Reset Vector
Command location 1 = Unallocated
Command location 2 = Unallocated
Command location 3 = Unallocated
Command location 4 = Interrupt Vector
Command location 5 = Usually the start of Program Code

#DEFINE AND JUMP LIMITS

Inevitably, there have been some quantity limits set into TK3. They are based on several years of experience with writing code for many EPE designs and seem like reasonable limits. If you think they should be extended, please tell us via the EPE Editorial Office. These are the principal ones in the Assembly program:

Equates       500
Defines       200
Labels        2000
Jumps (Calls) 2000
Columns       100 (of which you will normally use a maximum of five
              but 100 is allowed in case of program errors) 

If these limits are exceeded, an error condition will result. Whilst many error intercept routines have been incorporated in TK3, it cannot be guaranteed that every possible error condition had been allowed for.

SOURCE CODE LIMITS

There is no known limit to the length of source code text that can be handled by TK3, other than the limit imposed by your original text editor. Note that when clicking on the EDIT buttons to examine source code, the Notepad Editor (if this is the selected Editor - see General Notes) called by TK3 may sometimes respond by saying the file is too long for it to handle and asks if you wish to view it via WordPad. You may accept the offer. However, if you make changes to the text via Wordpad (or any other Text Editor you use) the text should then be saved as an ordinary text file (but still having the same Extension letters - e.g. .ASM - as the original file). Your source code may not assemble correctly if the file contains formatting commands generated by the Text Editor when saving as a non-text file.

With Notepad, DO NOT save as a "Text Document" since this causes a .TXT extension to be added. Save under the "All Files (*.*)" option and make sure you add the .ASM extension if this is not shown.

As with Toolkit Mk2 (later editions) you may use the TAB key in place of using the space-bar.

When assembling code, TK3 looks for gaps between commands etc, not caring how long those gaps are. It treats spaces and TAB commands equally when splitting command lines into their separate parts.

All source code commands are treated as though in capitals (upper case). You may write in either upper or lower case.

An exception to this is when data is included in single quotes as part of the command, for example: RETLW 'A' or RETLW 'a'. The character within the quotes retains its upper or lower case style.

CYCLIC ASSEMBLING/PROGRAMMING

When a successful assembly has been completed, a Send button is shown in the Programming sub-window, allowing immediate programming of the PIC. On completion of programming, an Edit button appears allowing you to make changes to the ASM program via the text editor. On exit from the editor, an Assemble button is shown, allowing immediate assembly of the revised program, following which the Send button reappears. And so the cycle continues until you click the Quit button.

It it worth noting that the most likely button that you wish to use has been made "active" (SetFocus) in response to pressing the keyboard <Enter> key. The active button is highlighted by having a dotted border outline. Cursor and Tab keys can cause the "focus" to be cycled around all command buttons on the active screen (although not necessarily in any logical order).

When the Edit or Assemble buttons are shown, a DIR button also appears, providing direct access to the directory (in ASM extension mode) if required without exiting the "cycle".

These facilities have been added by the author to speed the whole operation of writing and testing code "live".

INCLUDE FILES

TK3 supports the use of Include files. These may have any extension code (i.e. it does not have to be .INC, it could be .ASM or any other extension). More than one Include file can be called. Note, however, that TK3's directory (DIR) options only allow access to files having the extensions .ASM, .INC, .OBJ, .HEX and .MSG. Files having other extensions cannot be called in for viewing via the DIR buttons (but they can be viewed via the EDIT TXT and EDIT ANY buttons).

The call for loading an Include file may take any of three forms:

  .INCLUDE FILENAME 
  $INCLUDE FILENAME
  INCLUDE FILENAME

where FILENAME takes the form of, for example, P16F84.INC (an MPASM header file).

The INCLUDE command and FILENAME may be in upper or lower case letters. The call may be placed at the far left of the line (column 1), or indented (in the effective position of column 2), e.g.:

INCLUDE P16F84.INC

or
	
	 INCLUDE P16F84.INC

SPECIAL NOTE REGARDING .INC FILES 23FEB07

The access to .INC files has been amended.

All PIC-specific .INC files need to be in the Toolkit TK3 folder.

All other .INC files which specific to the project itself, need to be
held in the same folder as those for other files associated with the
project ASM being assembled.

With the introduction of V1.4, Include files may contain their own Equates and Defines, and may be placed anywhere in the main file code. It should be noted though that they must be placed earlier than any command in the main code that calls them.

It is preferable that those containing Equates and Defines should be placed near the top of the main code in the region where the main code Equates and Defines are placed and before the first ORG statement is made in the main code. Include files called in this region must not contain true program commands.

Other Include files may be placed at any suitable point within the body of the main code, and may be the first command of that code (i.e. at address location 5, the normal start of code for PIC16x8x, PIC16F87x and PIC16F62x devices.

It is important to note that Include files in the main body of the code must not contain their own Includes. 

Beware of using ORG statements within Include files since they may disrupt the correct assembly of the rest of the code.

When using/examining Microchip's Include header files (e.g. P16F84.INC) ignore Microchip's usage instructions, they are of no consequence to using TK3.

Include files must NOT contain Macros, which TK3 does not recognise.

WARN TICK BOX

When ticked, any Warnings generated while Assembly is made to be shown together with any Error messages. When unticked, only Error messages, if any, are shown. Thanks to e-friend John Waller for suggesting it!

CREATING NEW FILES

New files may be created from within TK3's Directory (DIR) screen. The files are automatically assigned the same directory (folder) path and extension that is current for the route from which DIR has been called. DO NOT attempt to change these parameters from within the Directory option, since unpredictable errors could occur. If you need to change a file's path and extension, this should only be done outside TK3's environment (i.e. through Windows' own facilities). 

File creation is limited to extensions .ASM, .INC (from the Assembly DIR buttons) and .MSG (via the Message DIR button). The Directory's file creation options are hidden when entering from other DIR buttons. If you think this limitation is unreasonable, tell us, but it seems
improbable that creation of OBJ and HEX files could ever be needed through manual data entry, or the creation of files that then need conversion from one dialect to another. Text files can be created via the EDIT TXT button.

In the Programming area on the main screen a Create New File button is included. This has been added so that readers initially unfamiliar with TK3 know where to create new source code files. It provides an identical access to the Directory as does the DIR button next to it, and either button may be used.

SIMULATION OPTION

The Mini Simulator option is only for use with PIC16F devices. It does not attempt to match the facilities of more sophisticated commercial simulators, such as provided by Microchip's MPLAB. It basically shows the behaviour of the commands in a program and the affects that they have upon the registers accessed. The following are not supported:

Interrupts
Access to Data Eeprom
PortB pullups
Sleep
Analogue inputs and other special I/O functions (e.g. RS232)
Timers, with the exception that a mock creation of a TMR0 rollover is generated in response to the simulator's own internal timer.

To run the simulator, the source code (ASM) file must first be assembled in the usual way. An additional file having the same name, but suffixed SIM, is created. This file is the one used by the simulator. It contains the command lines extracted from the ASM file, the hexadecimal values created during the assembly process (as also compiled into the normal HEX file), and line count values, which are the addresses within the PIC to which the values are downloaded during programming.

Unless you have created a SIM file for a particular ASM file, you cannot gain access to the Simulation screen.

When assembling an ASM file, unless it has the PIC type embedded in it (near the top of its code, in the form: LIST = P16F84, R = DEC) you MUST set the PIC type correctly via the usual option.

More information is given in the Notes within the Simulation screen.

ADDING YOUR OWN NOTES

These notes are displayed via an "Active" text editor and you may add your own notes to them, saving them to disk in the usual way.

