
********************************************************************* 
*
*    File name:  readme.tmp
*
*    File creation date:   May 15, 1998 
*
*
*    Revisions History:
*			   August 15, 1998
*                          Updated linker command file notes
*			   January 4, 1999
*                          Updated linker command file notes
*
********************************************************************* 


This file contains information which can assist the programmer 
in understanding the usage of a linker script ("command") file. 
Modifications to a linker command file may be required based 
upon such factors as main body code size, interrupt code size, 
ram variable usage, code section assignments, etc.. The linker 
script file can serve the programmer well once a greater 
understanding on "how to" modify the file is obtained.

This file presents one example describing how to modify a linker 
command file and its usage with Microchip generated object module 
code templates. Microchip generated linker command files (xxxxx.lkr) 
are located in the MPLAB directory.

The object modules located in the otemplate.zip file, downloaded 
from the WEB site, have been written and tested using MPLAB 3.40. 
with MPASM and MPLINK. Each of the object module code templates 
requires the use of the appropriate linker command file (xxxxx.lkr). 
A linker command file is an ASCII text file which is processed by 
the linker. Linker command files can be created and modified to 
control the operation of the linker.


The linker command file is used:

1. To define the target processor’s memory architecture.
2. To locate sections within the target processor’s memory.
3. To specify the size of the stack and, optionally, the target 
   memory where it resides.
4. To specify additional directories for the library/object 
   search path.
5. To specify additional directories for the linker command 
   file search path.
6. To specify additional object files and library files for linking.
7. To include additional linker command files.

Each line in a linker command file is either a directive or a 
comment. Any text following a ’//’ is ignored. The following 
directives are supported: LIBPATH, LKRPATH, FILES, INCLUDE, 
DATABANK, CODEPAGE, SHAREBANK, SECTION and STACK. Refer to the 
latest MPASM USER’S GUIDE with MPLINK and MPLIB (document number 
DS33014) for details on these directives and use of linker script 
files. 



*****  EXAMPLE DESCRIBED  *****
--------------------------------------------------------------------- 

The files in the otemplate.zip file were built (assembled) using 
the appropriate xxxxx.lkr file located in the MPLAB directory. The 
basic linker script required a minor modification in order to support 
the memory pages and interrupt vector(s) on the PICmicro. Without 
this modification a build error will result during the link process.

This minor modification deals specifically with changing the 
memory allocation size for codepages "vectors" and "page0" to 
support interrupt handling code. To better understand this 
modification let us look at a code excerpt from the 77temp0.asm 
file and the respective linker command file for the PIC16C77 (16c77.lkr)



******* EXCERPT FROM LINKER FILE (16C77.LKR)
---------------------------------------------------------------------  

LIBPATH  .

CODEPAGE   NAME=vectors  START=0x0      END=0x4      PROTECTED
CODEPAGE   NAME=page0    START=0x5      END=0x7FF
CODEPAGE   NAME=page1    START=0x800    END=0xFFF
CODEPAGE   NAME=page2    START=0x1000   END=0x17FF
CODEPAGE   NAME=page3    START=0x1800   END=0x1FFF
.
.
.

Looking at this excerpt, 5 codepages are defined and have been 
assigned a start and end address.  This information states that 
codepage "vectors" starts at address 0x000 and ends at 0x004. 
Likewise codepage "page0" starts at 0x005 and ends at 0x7FF. 
This information is used by the linker during the linking process. 
Note that the linker will only allow 5 assembly instructions 
from locations 0x000 to 0x004. 



From looking at a code excerpt from the 77tempo.asm file, (below), 
there are 2 initial code sections defined: RESET_VECTOR and 
INT_VECTOR. Code section RESET_VECTOR begins at 0x000 and 
INT_VECTOR begins at 0x004. These section definitions follow the 
actual architecture of the PIC16C77 PICmicro.


******* EXCERPT FROM 77tempo.asm FILE
--------------------------------------------------------------------- 

RESET_VECTOR  CODE    0x000       ; processor reset vector
        movlw  high  start        ; load upper byte of 'start' label
        movwf  PCLATH             ; initialize PCLATH
        goto   start              ; go to beginning of program


INT_VECTOR   CODE    0x004        ; interrupt vector location
        movwf   w_temp            ; save off current W register contents
        movf    STATUS,w          ; move status register into W register
        movwf   status_temp       ; save off contents of STATUS register

; isr code can go here 

		movf    status_temp,w     ; retrieve copy of STATUS register
		movwf	STATUS            ; restore pre-isr STATUS register contents
		swapf   w_temp,f
		swapf   w_temp,w          ; restore pre-isr W register contents
		retfie                    ; return from interrupt
 

From this code excerpt it can be seen that if the allocation size 
for codepage "vectors" is not modified the linker would generate 
an error, such as:
 
Error - section 'INT_VECTOR' can not fit the absolute section. 
        Section 'INT_VECTOR' start=0x00000004, length=0x00000010
Errors    : 1
Warnings  : 0


One approach to resolve this error is to modify the codepage sizes 
for "vectors" and "page0". Depending on the size of the interrupt 
service code, these 2 codepage sizes could be modified accordingly. 
As shown below the codepage vectors will allow 49 instructions from 
0x000 to 0x030.
 
CODEPAGE   NAME=vectors  START=0x0      END=0x30      PROTECTED
CODEPAGE   NAME=page0    START=0x31     END=0x7FF
CODEPAGE   NAME=page1    START=0x800    END=0xFFF
CODEPAGE   NAME=page2    START=0x1000   END=0x17FF
CODEPAGE   NAME=page3    START=0x1800   END=0x1FFF


A second approach is to keep the entry and exit code size constant 
for the interrupt vector routine and place the interrupt service 
code elsewhere in the main program body. In this approach if the 
interrupt service code size grows or shrinks the codepage size 
for vectors can be set and no ongoing adjustment is required. This 
method is shown below:


RESET_VECTOR  CODE    0x000       ; processor reset vector
      	movlw  high  start        ; load upper byte of 'start' label
        movwf  PCLATH             ; initialize PCLATH
        goto   start              ; go to beginning of program


INT_VECTOR   CODE    0x004        ; interrupt vector location
        movwf   w_temp            ; save off current W register contents
        movf    STATUS,w          ; move status register into W register
        movwf   status_temp       ; save off contents of STATUS register
        movf    PCLATH,w          ;
        movwf   pclath_temp       ; save off current state of PCLATH

        movlw   high ISR_HANDLER  ; read upper 8 bits of address for ISR_HANDLER  
        movwf   PCLATH            ; initialize PCLATH register
        call    ISR_HANDLER       ; call the interrupt service code
        
        movf    pclath_temp,w     ; retrieve copy of pre-interrupt PCLATH register
        movwf   PCLATH            ; restore pre-isr PCLATH register         
        movf    status_temp,w     ; retrieve copy of STATUS register
        movwf   STATUS            ; restore pre-isr STATUS register contents
        swapf   w_temp,f          ;
        swapf   w_temp,w          ; restore pre-isr W register contents
        retfie                    ; return from interrupt


MAIN    CODE                      ; define code section
start

; main program code goes here



ISR_HANDLER   CODE                ; define code section

; interrupt service code goes here

        return                    ; return to INT_VECTOR code section
 
        END                       ; required assembly directive



In this approach the size for codepage "vectors" is fixed. The 
interrupt service routine code termed "ISR_HANDLER" will now be 
placed in the main code body. The exact location will be 
determined at link time unless the user desires to place this 
code section in a selected codepage. (See MPASM USER’S GUIDE 
with MPLINK and MPLIB (document number DS33014) for details 
assigning code sections to codepages) 

CODEPAGE   NAME=vectors  START=0x0      END=0x12      PROTECTED
CODEPAGE   NAME=page0    START=0x13     END=0x7FF
CODEPAGE   NAME=page1    START=0x800    END=0xFFF
CODEPAGE   NAME=page2    START=0x1000   END=0x17FF
CODEPAGE   NAME=page3    START=0x1800   END=0x1FFF

While there may be additional methods for resolving an issue 
like this, the main emphasis of the material presented is to 
make the programmer aware of the linker file and the possibility 
that changes may be required.


--------------------------------------------------------------------- 
Important Notes:
--------------------------------------------------------------------- 

LINKER COMMAND FILES

Sample linker command files are shipped with MPLINK.  Not all
processors have a specific linker command file.  It is expected
that changes will be required for a particular application.
The samples are meant as templates for creation of an
application-specific linker command file.


Use this file             with these processors
--------------            ----------------------------------
12C508.LKR                12C508, 12C508A, 12CE518
12C509.LKR                12C509, 12C509A, 12CE519
12C671.LKR                12C671, 12CE673
12C672.LKR                12C672, 12CE674
14000.LKR                 14000
16C505.LKR                16C505
16C52.LKR                 16C52
16C54.LKR                 16C54, 16C54A, 16C54B, 16CR54,
                          16CR54A, 16CR54B, 16CR54C
16C55.LKR                 16C55
16C554.LKR                16C554, 16C620, 16C620A
16C556.LKR                16C556, 16C621, 16C621A
16C558.LKR                16C558, 16C622, 16C622A
16C56.LKR                 16C56, 16C56A, 16CR56A
16C57.LKR                 16C57, 16CR57A, 16CR57B
16C58.LKR                 16C58A, 16C58B, 16CR58A, 16CR58B
16C61.LKR                 16C61
16C62.LKR                 16C62, 16C62A, 16C62B, 16CR62, 16C64, 16C64A,
                          16CR64, 16C72, 16CR72, 16C72A
16CE623.LKR               16CE623
16CE624.LKR               16CE624
16CE625.LKR               16CE625
16C63.LKR                 16C63,  16C63A, 16C65,  16C65A, 16C65B, 16CR63,
                          16CR65, 16C73,  16C73A, 16C73B, 16C74,  16C74A,
                          16C74B
16C641.LKR                16C641
16C642.LKR                16C642
16C66.LKR                 16C66, 16C67
16C661.LKR                16C661
16C662.LKR                16C662
16C71.LKR                 16C71
16C710.LKR                16C710
16C711.LKR                16C711
16C715.LKR                16C715
16C76.LKR                 16C76, 16C77, 16F876, 16F877
16C773.LKR                16C773, 16C774
16C84.LKR                 16C84
16C923.LKR                16C923, 16C924
16F83.LKR                 16F83, 16CR83
16F84.LKR                 16F84, 16CR84
16F873.LKR                16F873, 16F874
17C42.LKR                 17C42
17C42A.LKR                17C42A, 17CR42
17C43.LKR                 17C43, 17CR43
17C44.LKR                 17C44
17C752.LKR                17C752, 17C762
17C756.LKR                17C756, 17C756A, 17C766


------------------------------------------------------------
How To Contact Microchip
------------------------------------------------------------

On-Line Support
---------------
Microchip provides on-line support on the Microchip World
Wide Web (WWW) site.  The web site is used by Microchip as a
means to make files and information easily available to
customers. To view the site, the user must have access to
the Internet and a web browser, such as Netscape or
Microsoft Explorer. Files are also available for FTP
download from our FTP site.

Connecting to the Microchip Internet Web Site      
---------------------------------------------
The Microchip web site is available by using your favorite
Internet browser to attach to:
 
	www.microchip.com

The file transfer site is available by using an FTP service
to connect to: 

	ftp://ftp.futureone.com/pub/microchip

The web site and file transfer site provide a variety of
services. Users may download files for the latest
Development Tools, Data Sheets, Application Notes, User's
Guides, Articles and Sample Programs. A variety of Microchip
specific business information is also available, including
listings of Microchip sales offices, distributors and
factory representatives. Other data available for
consideration is:

	* Latest Microchip Press Releases

	* Technical Support Section with Frequently Asked
          Questions 

	* Design Tips

	* Device Errata

	* Job Postings

	* Microchip Consultant Program Member Listing

	* Links to other useful web sites related to
	  Microchip Products

 	* Conferences for products, Development Systems,
	  technical information and more

	* Listing of seminars and events


