Porting from MPASM to PIC-AS.

Insights 25th May 2021

Contents
What is MPASM ? ................................................................................................................................ 2
What is PIC-AS ? ................................................................................................................................. 2
Reference Documents ......................................................................................................................... 2
Context of Project ................................................................................................................................. 3
Summary ............................................................................................................................................... 3
Insights ................................................................................................................................................... 4
PIC-AS Command Line ....................................................................................................................... 7
18F specifics ......................................................................................................................................... 8
Midrange 10f, 12f and 16f specifics................................................................................................. 10
Debugging ........................................................................................................................................... 14

Version 0.9b
What is MPASM ?

MPASMx - v5.87 is the last published version of MPASM assembler.

The last chip added to MPASM was the 18FxxQ43. So, any chip released
after this (Q10s, Q41s etc) will not work.

The software is Windows 32bit. It should work on a Windows 64bit OS

with the 32bit support.

A standalone installer for MPASMx - v5.87 can be found

here: https://sourceforge.net/projects/gcbasic/files/Support
Files/MicrochipCompilers/

What is PIC-AS ?

PIC-AS - v2.32 is the latest version of the PIC-AS assembler driver. This is
a standalone driver and you do not need MPLAB-X to assemble your
source code.

A standalone installer for PIC-AS- v2.32 can be found

here: https://sourceforge.net/projects/gcbasic/files/Support
Files/MicrochipCompilers/

Reference Documents – Three Microchip reference documents have

been published. They are:
MPLAB® XC8 PIC Assembler User's Guide for Embedded Engineers

https://ww1.microchip.com/downloads/en/DeviceDoc/MPLAB%20XC8%20PIC%20As
sembler%20User%27s%20Guide%2050002974A.pdf

MPLAB® XC8 PIC® Assembler User's Guide

https://ww1.microchip.com/downloads/en/DeviceDoc/XC8-PIC-Assembler-UG-for-
EE-50002994A.pdf

MPASM™ to MPLAB® XC8 PIC® Assembler Migration Guide

https://ww1.microchip.com/downloads/en/DeviceDoc/MPASM%20to%20MPLAB%20
XC8%20PIC%20Assembler%20Migration%20Guide%2050002973A.pdf
Context of Project

Within Great Cow BASIC ( a compiler for LGT/AVR and PICs) we use
ABSOLUTE addressing and these insights therefore apply to ABSOLUTE
addressing. But, most of these insights are useful in any mode of
addressing.

I have completed an extensive project to ensure Great Cow BASIC

compiler supports PIC-AS (for LGT/AVR and PICs).

This document covers the PIC port from MPASM to PIC-AS.

Summary

You can port an existing ASM to PIC-AS just take a little care.


Insights

1. Source file: The source file has the extension of `.S`. The .S implies
the PIC-AS driver uses the -xassembler-with-cpp option. The assembly
source code will therefore be pre-processed.

The format of .S source file strict.

A huge unpublished bug is the placement of the #include <xc.inc> statement.

This statement MUST come after all the CONFIG statement. This is order
is strict and NOT published as such by Microchip.

2. Case sensitivity: Everything, in the .S source, is case sensitive and

you cannot disable case sensitivity.

For the Great Cow BASIC compiler we validate everything by completing a

reverse lookup into the PIC-AS source/setup files, and, we use
UPPERCASE for the .S source file except of explicit CONFIG items. This
approach ensures the registers are correct, however, for register.bits there
is a totally new naming convention. So, for register.bit the reverse lookup
time overhead is a little too long so we simply use the constant value. –
The source still shows the register.bit string name.

Recommend. Using uppercase throughout except for the config items

that require case sensitive entries.

The reverse lookup PIC-AS files are very easy to determine. The following
is a pic16f877a example. Note the PIC-AS version number and the
chipname.

Code:

; Reverse lookup file(s)

; C:\Program Files\Microchip\xc8\v2.32\pic\include\proc\pic16f877a.inc
; C:\Program Files\Microchip\xc8\v2.32\pic\dat\cfgmap\16f877a.cfgmap

Recommend. Use these PIC-AS source files to validate the registers

and register.bits.

3. Labels: All labels MUST be terminated with a colon.

4. Missing stuff: Depending on your chip architecture certain directives

are missing, but, you can put them back to make existing code work.
Examples are BANKED, ACCESS, UPPER ...
Add the following code segment to an 18f solution to resolve.

Code:

;Explicit PIC-AS constants to resolve the craziness of the PIC-AS syntax

;These are therefore the same as MPASM
#define BANKED b
#define ACCESS a
#define UPPER low highword

Recommend. Just add the code segment shown above.

5. Config: The config definition is strict. You just need to have the configs
one per line. As config names are strict - we complete a reverse lookup to
ensure the case is correct.

6. PSECTs: Absolute mode is supported and works well. The set of

pages using a directive is simple ... once you have it documented. See
PSECT details below to specify the absolute mode.

7. Memory: With absolute addressing the memory management for our

compiler implementation is easier than using the PIC-AS memory
management.

We use the EQU method - make the variable name global (for debugging).
Code:

;Set aside RAM memory locations for variables. All variables are global.
GLOBAL DELAYTEMP
DELAYTEMP EQU 112 ; 0X70
GLOBAL DELAYTEMP2
DELAYTEMP2 EQU 113 ; 0X71
GLOBAL SYSWAITTEMPMS
SYSWAITTEMPMS EQU 114 ; 0X72
GLOBAL SYSWAITTEMPMS_H
SYSWAITTEMPMS_H EQU 115 ; 0X73

The memory usage reports from PIC-AS are not very good and EQUs are
not reported in the log but you can verify in the LST file.

8. FCALL and LJMP: The PIC-AS driver is smart. Too smart. It will
reject CALL and GOTOs to another page. There is NO level of magic
coding (by you) to avoid not using FCALL and LJMP will succeed. These
two instructions are automatically expanded by PICAS (into three
instructions). You will have to change to FCALL and LJMP.

9. ALIGN: Specific to the 18F you must ensure your code is aligned
correctly. See the 18f section below for details.
10. Bugs: A number of bugs existing in the 10f, 12f and 16f PIC-AS
solution. See the 10f, 12f and 16fs section below for details.

11. Reserved Words: There are number of new/unpublished reserved

words. These includes LINE and HEX – there may be many others. As
LINE and HEX are used within Great Cow BASIC for drawing a line on a
GLCD and formatting a number to string respectively these are required.
To resolve redefine your methods (line() to _line() and hex() to _hex() and
then use a constants to ensure PIC-AS uses the newly renaming methods.

Code:

#define hex _HexPICAS

#define line _line

Know Reserved Words

LINE
HEX
ERROR
PIC-AS Command Line
This is the command line used:

-mcpu=%ChipModel% "%Fn_NoExt%.S" -msummary=-mem,+psect,-class,-hex,-file,-sha1,-sha256,-

xml,-xmlfull -Wl -mcallgraph=std -mno-download-hex -o"%Fn_NoExt%.hex" -Wl,-
Map="%Fn_NoExt%.map" -Wa,-a

Replace %ChipModel% with the chipname

Replace "%Fn_NoExt%.*" with the location of your .S source file.
Replace "%Fn_NoExt%.hex with your filename

-msummary states the reporting

-Wa,-a is the LST file this is very important.
18F specifics

This sections is specific to 18F chips. This covers PSECTS and Alignment
of code.

PSECTs

PSECTS - short for program sections - are containers that group and hold
related parts of the program, even though the source code for these parts
might not be physically adjacent in the source file, or may even be spread
over several modules.

The principle of operation is to manage the PSECT using absolute

addressing. Where PIC-AS will complete no optimisation.

Use `delta = 1, abs` and, you need to add the RESETVEC. As follows:
Code:

;Explicit PIC-AS constants to resolve the craziness of the PIC-AS syntax

;These are therefore the same as MPASM
#define BANKED b
#define ACCESS a
#define UPPER low highword

PSECT RESETVEC,delta=1, abs

RESETVEC:

…
lots of code
…

end bit of code

;
; Declare Power-On-Reset entry point
;
END RESETVEC

Alignment

Unlike MPASMx the alignment of instructions is NOT automatic. You need

to ensure an instruction is located in the address space correctly. You need
to add ALIGN 2 when appropriate. Typically, you need to add after table
data (as they may be an odd number of bytes and this WILL cause
misalignment.

Example. In this example the ALIGN 2 above ;SOURCE: PICAS.H (7)

ensure the MOVLW 2 is in the correct address space.
Code:
GLOBAL STRINGTABLE5
STRINGTABLE5:
DB 2,45,45

ALIGN 2;X3

GLOBAL STRINGTABLE6
STRINGTABLE6:
DB 33,69,110,100,32,111,102,32,69,69,80,114,111,109,32,80,114,111,103,114,97,109
DB 32,97,110,100,32,68,105,115,112,108,97,121

ALIGN 2;X3

;********************************************************************************

;SOURCE: PICAS.H (7)

GLOBAL FN__HEXPICAS
FN__HEXPICAS:
;_HexPICAS(0) = 2
MOVLW 2
BANKSEL SYS_HEXPICAS_0
MOVWF SYS_HEXPICAS_0,BANKED
Midrange 10f, 12f and 16f specifics
This section is specific to 10f, 12f and 16f chips. This covers PSECTS
and known bugs.

PSECTS

The principle of operation is to manage the PSECT using absolute

addressing by defining each page of PROGMEM as a separate PSECT
and PIC-AS will complete no optimisation.

Use delta = 2, abs mode and you need to add the RESETVEC. As follows:

PSET per page (where a PSECT is added in the chip has that specific
page).

Code:

PSECT PROGMEM0,delta=2, abs

RESETVEC:
;VECTORS
ORG 0
PAGESEL BASPROGRAMSTART
GOTO BASPROGRAMSTART
ORG 4
RETFIE

;********************************************************************************

…
lots of code
…

;START OF PROGRAM MEMORY PAGE 1

PSECT PROGMEM1,CLASS=CODE,SPACE=SPACE_CODE,DELTA=2, ABS, OVRLD
ORG 2048

…
lots of code
…

;START OF PROGRAM MEMORY PAGE 2

PSECT PROGMEM2,CLASS=CODE,SPACE=SPACE_CODE,DELTA=2, ABS, OVRLD
ORG 4096

…
lots of code
…

;START OF PROGRAM MEMORY PAGE 3

PSECT PROGMEM3,CLASS=CODE,SPACE=SPACE_CODE,DELTA=2, ABS, OVRLD
 ORG 6144

…
lots of code
…

;
; Declare Power-On-Reset entry point
;
END RESETVEC

Bugs
The v2.32 PIC-AS driver has some horrid bugs.

ERRANT EXPANSION: The main mid-range bug is the addition of extra

instructions (in error). These extra instructions WILL cause your code NOT
to fit on a page. You will get page overruns. This is slated for fixing in
v2.35. The instructions that cause these extra instructions include BTFSS,
BTFSC, INCFSZ and DECFSZ. The picture below show the expand code
with the errant 0x3194 prior to the 0x0BDA.

A workaround could be to replace these errant expansions with macros as

follows:

Code:

#define BTFSS mybtfss

#define BTFSS mybtfsc

mybtfss MACRO arg1, arg2

arg3 set ( arg2 << 7 )
arg4 set ( arg1 AND 127 )
dw arg3 + arg4 + 0x1C00
ENDM

mybtfsc MACRO arg1, arg2

arg3 set ( arg2 << 7 )
arg4 set ( arg1 AND 127 )
dw arg3 + arg4 + 0x1800
ENDM

These macros replace the BTFSx instructions with DW instructions. The

DW are the same hex code values as the BTFSS and BTFSC instructions,
however, this approach prevents PIC-AS from expanding as PIC-AS treats
DW as dataword. The downside of this ? The LST will show the DW not
BTFSx instructions.

REPORTING: The error report is wrong when the PSECT delta=2. Just
divided the memory address that has the error by 2. Annoying.

The picture below shows an error message. This address of 0x2000

should be 0x1000. The picture also explain the location of the source
of the page overrun and one of (the many) BTFSx that have been
expanded shown in the yellow box.

BANKISEL: BANKISEL is not supported. BANKISEL is used on some

chip for indirect addressing. So, you can add a relatively simple macro to
restore BANKISEL.

Add this macro if BANKISEL support is required.

BANKISEL MACRO reg

;BANKISEL macro to restore missing Directive.
 if reg < 0x100
;MESSG "Bankvalue < 256 - bcf"
bcf STATUS, 7
else
;MESSG "Bankvalue > 256 - bsf"
bsf STATUS, 7
endif
ENDM
Debugging

My advice. Add GLOBAL to all labels and variable definitions. This makes
debugging a lot easier.