TOOLKIT GENERAL INFO

As requested by readers, here's a summary of some the matters
relating to Toolkit, MPASM and TASM. John Becker 19JAN01

MICROSOFT DESIGNATED PIC COMMANDS RECOGNISED BY TOOLKIT MK2 V2.4

 Command	Flags Affected	Description             

ADDWF	f,d	C, DC, Z	Add W and f             
ANDWF	f,d	Z		AND W with f
CLRF	f	Z		Clear f
CLRW	-	Z		Clear W
COMF	f,d	Z		Complement f
DECF	f,d	Z		Decrement f
DECFSZ	f,d	-		Decrement f, skip if 0
INCF	f,d	Z		Increment f
INCFSZ	f,d	-		Increment f, skip if 0
IORWF	f,d	Z		Inclusive OR W with f
MOVF	f,d	Z		Move f
MOVWF	f	-		Move W to f
NOP	-	-		No operation
RLF	f,d	C		Rotate left f through Carry
RRF	f,d	C		Rotate right f through Carry
SUBWF	f,d	C, DC, Z	Subtract W from f
SWAPF	f,d	-		Swap nibbles in f
XORWF	f,d	Z		Exclusive OR W with f
BCF	f,b	-		Bit clear f
BSF	f,b	-		Bit set f
BTFSC	f,b	-		Bit test f, skip if 0
BTFSS	f,b	-		Bit test f, skip if 1
ADDLW	k	C, DC, Z	Add literal and W
ANDLW	k	Z		AND literal with W
CALL	k	-		Call subroutine
CLRWDT	TO, PD			Clear Watchdog Timer
GOTO	k	-		Go to address
IORLW	k	Z		Inclusive OR literal with W
MOVLW	k	-		Move literal to W
RETFIE	-	-		Return from interrupt
RETLW	k	-		Return with literal in W
RETURN	-			Return from subroutine
SLEEP	-	TO, PD		Go into standby mode
SUBLW	k	C, DC, Z	Subtract W from literal
XORLW	k	Z		Exclusive OR literal with W

MPASM SHORTHAND COMMANDS

The following shorthand commands are recognised by MPASM
and by Toolkit Mk2 when translating from MPASM to TASM.
They may not be recognised by other non-MPASM Assemblers.

Command		TK3 coding		Meaning

ADDCF f,d 	BTFSC STATUS,C		Add Carry to File
		INCF f,d

ADDDCF f,d	BTFSC STATUS,DC		Add Digit Carry to File
		INCF f,d

B k		GOTO k			Branch to

BC k		BTFSC STATUS,C		Branch on Carry to k
		GOTO k

BDC k		BTFSC STATUS,DC		Branch on Digit Carry
		GOTO k

BNC k		BTFSS STATUS,C		Branch on No Carry
		GOTO k

BNDC k		BTFSS STATUS,DC		Branch on No Digit Carry
		GOTO k

BZ k		BTFSC STATUS,Z		Branch on Zero
		GOTO k

CLRC		BCF STATUS,C		Clear Carry

CLRDC		BCF STATUS,DC		Clear Digit Carry

CLRZ		BCF STATUS,Z		Clear Zero

MOVFW,f		MOVF f,W		Move File to W

NEGF f,d	COMF f,F		Negate file
		INCF f,d

SETC		BSF STATUS,C		Set Carry

SETDC		BSF STATUS,DC		Set Digit Carry

SETZ            BSF STATUS,Z            Set Zero

SKPC		BTFSS STATUS,C		Skip on Carry

SKPDC		BTFSS STATUS,DC		Skip on Digit Carry

SKPZ		BTFSS STATUS,Z		Skip on Zero

SUBCF f,d	BTFSC STATUS,C		Subtract Carry from File
		DECF f,d

SUBDCF f,d	BTFSC STATUS,DC		Subtract Digit Carry from File
		DECF f,d

TSTF f		MOVF f,F		Test File

Where:
d = destination (0 or 1 - W or F)
f = file
k = literal value

GRAMMAR DIFFERENCES FOR TASM AND MPASM

The following grammar statements are recognised by Toolkit MK2
in both MPASM and TASM modes (except Octal):

	TASM		MPASM

Decimal	153		D'153'
Hex	$2B		H'2B' or 0x2B
Binary	%10010110	B'10010110'
ASCII	'C'		'C' or A'C'
Octal	-		O'777' (not recognised by Toolkit MK2)

	.EQU		EQU
	.ORG		ORG
	.END		END
	LABEL:		LABEL

#DEFINE definitions are usually recognised.

TOOLKIT LIMITATIONS

Toolkit does not recognise:
Macro definitions or routines.
Values in the form of $+1 or $-2 etc.
Commands such as IF, END IF, ELSE, WHILE, Y==8 etc.
Data statements.
Any form of PIC BASIC language.

Hex files containing data for PIC addresses 0-3 are likely to cause errors.

Hex files containing PIC addresses greater than the capacity of the PIC
being used are likely to cause errors - these addresses typically relate
to PIC configuration data.

Configuration data in ASM and HEX files may cause errors - Toolkit does not
attempt to use such data. Configuration can only be done through the
designated option on the main screen.

Simple "Include" (INC) files are recognised in TASM assembly (since V2.4)
but not in conversion between TASM/MPASM. "Tab" commands may be used in ASM
and INC files.

MPASM assembled files are in HEX format whose structure follows. Note that
MPASM source code (ASM) cannot be directly assembled by Toolkit MK2.  

MPASM HEX FILE STRUCTURE

MPASM hex code example - :NN AAAA RR MMLL MMLL MMLL MMLL CC TT

where:

":"      = record start character
"NN"     = byte quantity in line as hex value
"AAAA"   = address of first byte in hex
"RR"     = record type in hex (00 except last which is 01)
"MMLL"   = data bytes in order of MMLL in hex (NB MMLL = MSB/LSB for MPASM
           (but might be LSB/MSB for some non-MPASM hex files. Toolkit only
           recognises MPASM hex format) 
"CC"     = check sum in hex
"TT"     = line terminator (carriage return, line feed)

Checksum defined as:

sum      = byte count + address hi + address lo + record type + (sum of all data bytes)
checksum = (-sum) AND 255

HISTORY AND THE NEXT GENERATION

TASM source code (ASM) files are assembled to OBJ (object) binary format
held and sent to the PIC sequentially. Historically such files have data
for PIC locations 0-3 omitted, this being added at the time of sending the
file to a PIC, taking the form of GOTO 5, NOP, NOP, NOP. It is up to the
user to determine whether or not files have been suitably processed in
relation to PIC addresses 0-3 during translation. The protocol was
established with the original EPE PIC16C84 Programmer by Derren Crome in
1996 and applies to all TASM-coded files since then. The programmer
equally applied to the PIC16C84 and PIC16F84.

Toolkit MK1 was introduced to overcome the mains problems caused by
dual-dialect formats in which EPE PIC codes could be written by
readers. A 12V to 14V supply was required with the hardware. Switching
was controlled by the computer, whereas Derren's required manual switching,
as do the PIC Tutorial and PICtutor (CD-ROM version) boards. The latter
continue to be run under Derren's original TASM programmer software.

Toolkit MK2 continued computer control over all programming switch
functions, but now included generation of 12V by a dedicated chip allowing
operation from a 9V supply. Hardware facilities for the then newly arrived
PIC16F87x series were added. Subsequent software versions up to V2.4
added extra options as suggested by readers and in the light of my own
experience. Notable additions were the facilities to read back program code
from the PIC and to directly access its EEPROM data memory.

Note that Toolkit MK2 does not (and never will) claim to offer full
compatibility with all files created using MPASM grammar. If statements occur
in files which Toolkit does not recognise, it is up to the user to translate
the commands to a more simple form. I will be pleased to learn of any which
are found.
 
Most of Toolkit MK2's principal limitations will be removed in Toolkit For
Windows (TK3) being prepared for EPE release in Autumn 2001. It will be far
more versatile in many aspects. You are invited to make suggestions for
additional TK3 facilities.

Please send comments and suggestions to me via the EPE Editorial office.
Please DO NOT make them via the EPE Chat Zone as I do not necessarily read
it regularly - I might not get to see your suggestions!

John Becker 19JAN00

