A Guide To PIC Microcontroller Documentation/Documentation structure dev tools manufacturing

Development Tools and Manufacturing Documentation Structure

Once the documentation for the processor architecture, chosen programming language and development tools have be sourced it is time to look at the hardware tools needed for code development on the target controller and information on flash programming for production purposes. The main documentation areas have previously been identified as:

• Microcontroller or DSC documentation
• Programming language tools documentation
• Integrated Development Environment (IDE) documentation (if used)
• Hardware debugger and/or programmer documentation
• Flash program memory programming documentation

In this section, the last two points will be examined in more detail.

The hardware debugger and programmer documentation helps us to understand the capabilities and limitations of the available tools needed to debug the application we will develop on the target hardware. This encompasses everything from number of available debugging breakpoints and controller resources needed to support debugging to recommended circuitry to guarantee successful in-circuit programming during manufacturing.

For those keen to develop their own programming tools, either for their own manufacturing facilities or for the purpose of selling programming tools for the PIC® family of microcontrollers, the program memory programming documentation must be examined in detail.

Hardware debugger and/or programmer documentation

The debugging and programming can be split into two core groups; debuggers and in-circuit emulators that can be used as programmers as well; and tools which only have programming capability. All of these tools are primarily designed to work in conjunction with the MPLAB® IDE or other proprietary Windows GUI software, although occasionally command line interfaces are also offered.

In-Circuit Debuggers (ICD) and In-Circuit Emulators (ICE)

The latest generation of debuggers and in-circuit emulators support almost all of the current Microchip controller product portfolio and have the same visual interface within the MPLAB® IDE. The decision which tool to use depends on the features you need from the tool for debugging, whether those features are also supported by the microcontroller you wish to use and how much money you are prepared to spend. The three main current tools, PICkit™ 3, ICD 3 and REAL ICE™, are compared in the following table:

Feature	PICkit™ 3	MPLAB® ICD 3	MPLAB® REAL ICE™
USB Speed	Full (12Mbps)	Full/High (12/480Mbps)	Full/High (12/480Mbps)
USB Powered	Yes	Yes	Yes
Can supply power to target	Yes (30mA @ 1.8V-5.0V)	Yes (100mA @ 3.0V-5.0V)	No
Breakpoints	Simple	Complex	Complex
Software Breakpoints	No	Yes	Yes
Standalone Programming Support	Yes	No	No
Native Trace	No	No	Yes
Other Trace (over serial interface)	No	No	Yes
Data Capture/Run Time Watch	No	No	Yes
Logic/Probe Triggering	No	No	Yes
High Speed Debug Interface Support	No	No	Yes
Support for Opto-Isolated Debug	No	No	Yes

The table only makes a feature comparison of the three main tools and doesn't help much if you are trying to choose a tool for development on a particular microcontroller or for a particular application. The following attempts to provide a more expansive description of each tool with a list of appropriate documentation:

• PICkit™ 3 - An entry level tool with the lowest price-point aimed to suit every budget. Suitable for use with all three families of controller, although programming the flash memory of the larger PIC18, PIC24, dsPIC and PIC32 devices is considerably slower (35 seconds for a 512kB memory compared to 10 seconds for an ICD 3 or REAL ICE™) than with the more feature rich ICD 3 and REAL ICE™. Ideally suited for development on the smaller memory type 8-bit family devices which, generally speaking, cannot benefit from the advanced debug features of the other two debug tools.
  • Set Up Poster - Simple "getting started" information in poster format - DS51792
  • User's Guide - Detailed description of using the tool for development - DS51795
  • Debug Express Lessons - Series of 12 practical exercises using a PIC18F45K20, PICkit™ 3, MPLAB® Compiler for the PIC18, and the MPLAB® IDE - DS41370

• ICD 3 - A mid-entry debug tool for those with a larger budget. Suitable for general to complex code development on all controller families. Highly recommended for PIC18, 16-bit and 32-bit development where the more advanced debug features can be utilised and the larger flash memories can be more quickly programmed.
  • Quick Start Poster - Simple "getting started" information in poster format - DS51765
  • User's Guide - Detailed description of using the tool for development - DS51766
  • Design Advisory - Provides additional information on common operation issues, many of which apply to the PICkit™ 3 and REAL ICE™ too - DS51764

• REAL ICE™ - The top-end debug tool ideally suited for development of complex applications. Probe inputs and outputs can be used to generate or react upon external signals. Instrumented trace is valuable for analysing code flow in complex or multi-threaded applications. With the addition of the "Performance Pak" [sic] debug data and trace information can be transferred at higher speed between the REAL ICE™ and target controller. This debugger, in conjunction with the "Performance Pak" and "Opto-Isolator" module, is the only debugging option suitable for debugging on microcontrollers in high-voltage applications.
  • MPLAB® REAL ICE™ Poster - First steps for setting up the REAL ICE™ for debugging; includes set up of "Performance Pak" - DS51749
  • User's Guide - Detailed explanation of REAL ICE™ features; covers "Performance Pak" and "Opto-Isolator" usage too - DS51616

TIP! - MPLAB® IDE, if installed, has release specific information for all of these tools. Look at [DRIVE]:\<INSTALL PATH>\Microchip\MPLAB IDE\Readmes. The "Device Support.html" file lists the support status of each microcontroller for all of the currently supported tools!

Mature In-Circuit Debuggers and In-Circuit Emulators

There are several tools which are still referenced in documentation, help files and software tools such as MPLAB™ IDE. These are briefly mentioned here with notes on where to find relevant documentation should you acquire one of these tools.

• PICkit™ 2 - forerunner to the PICkit™ 3. Supported most microcontrollers of all families until the launch of the PICkit™ 3, after which the support for future newly introduced microcontrollers will be reduced or even phased out. Originally conceived as a pure budget programmer tool, the PICkit™ 2 acquired its debugging capability later in its product life. As a programming tool it is supported by its own Windows GUI allowing it to be used without the MPLAB® IDE. Features a command line tool suitable for production programming or use with 3rd Party software (e.g. MatrixMultimedias FlowCode development environment) and a "Programmer-To-Go" mode allowing the PICkit™ 2 to be used as a stand-alone programmer (i.e. without a connection to a host PC) as long as the target circuit provides the tool with power. Currently the only tool support under Windows, Linux and MAC OS.
  • Documentation - all relevant documentation and software can be found at www.microchip.com/pickit2
• ICD 2 - forerunner to the ICD 3. First "low-cost" in-circuit debug tool allowing developers to debug their application on the actual microcontroller they intended to use while the microcontroller was physically soldered in to the application circuitry. The target microcontroller needed a matching "debug module", implemented on the silicon, for the debug to function and also required two I/O pins for the data connection to the tool. Featured both debugging and programming facility supported through the MPLAB® IDE. With the introduction of the ICD 3 little if any major further support for newly released microcontrollers is expected.
  • Documentation - all relevant documentation can be found at www.microchip.com/icd2
• ICE 2000 - a hardware, full-feature emulator complete with hardware breakpoint support, trace and full-speed emulation. Supported almost all the PIC12, PIC16, PIC17 and earlier PIC18 microcontrollers. Connection to the PC used the parallel interface. The device consisted of three parts; the "POD", the main part of the emulator connected to the PC; a "processor module" which supported a small group or family of similar devices; and a "device adaptor" which allowed the processor adaptor to be connected to the circuit in place of the microcontroller device which was planned to be used. Due to the complexity of this tool the purchase cost was very high, and a move to another controller device warranted further investment in the matching device adaptor, processor module or both. There is no further development of this tool.
  • Documentation - all relevant documentation can be found at www.microchip.com/ice2000
• ICE 4000 - essentially the next generation in-circuit emulator follow-up to the ICE4000, supporting the PIC18 and the then new 16-bit dsPIC30 devices. Had improved supply voltage support, deeper trace buffers, unlimited breakpoints, external trigger input and signal output for synchronisation with external tools (e.g. oscilloscope) and a USB interface to the PC. Acceptance and use was never as broad as the ICE2000, partially due to similar high purchase and maintainance costs as the ICE 2000 and partially due to the attractiveness of the new, and significantly cheaper, ICD 2 despite its comparatively reduced debugging capability. There is no further development of this tool.
  • Documentation - all relevant documentation can be found at www.microchip.com/ice4000

Programming Tools

The need for a dedicated programming tool is somewhat reduced due to the fact that all of the debugging tools have a pure programming mode. However, for those situations where a pure programming device is needed Microchip currently offers three different programming tools. The main tool is the MPLAB® PM3, suited for use in a production programming environment for small production runs. Larger production runs are supported by programmers or gang programmers from various 3rd party partners. The following tables summarizes the main capabilities of the three currently supported programming tools:

Feature	MPLAB® PM3	PICSTART® Plus	PRO MATE® II
USB Interface	Yes - Full Speed (12Mbps)	No	No
RS-232 Interface	Yes	Yes	Yes
In-Circuit Serial Programming (ICSP)	Yes - Native Support	No	Yes - Adaptor Required
PC Host Mode	Yes	Yes	Yes
Safe Programming Mode	Yes	No	Yes
Standalone Programming Mode	Yes	No	Yes
DIP ZIF Socket	No	Yes	No
Interchangeable Programming Sockets	Yes	Limited - Adaptor Required	Yes
Serialisation Mode	Yes	No	Yes
DOS Command Line Support	Yes	No	Yes

The following provides a little more detail on the individual programming tools:

• MPLAB® PM3 - A full programming tool supporting (with few exceptions) all of the microcontroller products manufactured by Microchip. Through interchangeable programming sockets the wide array of packages in which the microcontrollers are delivered can be programmed. In-circuit programming is also supported through the ICSP interface for controllers that are already soldered onto a circuit board. Multiple ".hex" files can be saved on an SD or MCC card allowing for stand-alone operation. A "safe-mode" allows the programmer to reduce the PM3s functionality to programming only, ideal for on a production line, simplifying use by reducing functionality to avoid mistakes or access to other ".hex" files saved on the system. Serialisation and a DOS command line allow further functionality without the need to use the MPLAB® IDE. For those wishing to move from PROMATE® II to the PM3 an adapter is available allowing the PROMATE® II programming sockets to be used with the PM3.
  • Quick Start Poster - Simple "getting started" information in poster format - DS51450
  • User's Guide - Detailed description of the tool's programming modes and functionality - DS51464
  • Design Guide for ICSP™ - Additional poster format documentation providing important design information for the In-Circuit Serial Programming (ICSP™) of controllers already soldered onto a circuit board - DS51474

All PM3 documentation is to be found on the PM3 product page at www.microchip.com/pm3

• PICSTART® Plus - A entry-level programming tool ideally suited for devices in DIP/DIL packages. Adapter boards are also available with alternative sockets for different types of packages. Suitable for PIC10, PIC12, PIC16, PIC17, and earlier PIC18 products (not 'K' or 'J' types).
  • User's Guide - Detailed description of using the tool for programming within the MPLAB® IDE environment - DS51028

All PICSTART® Plus documentation is to be found on the PICSTART® Plus product page at http://www.microchip.com/picstartplus

• PROMATE® II - The forerunner to the PM3, the PROMATE® II is no longer available for purchase, but support and accessories are still available for the immediate future. Not as feature rich as the PM3, and the RS-232 interface restricts the programming speeds for the larger flash memory devices available today. Suitable for PIC10, PIC12, PIC16, PIC17, earlier PIC18 products (not 'K' or 'J' types) and dsPIC30.
  • User's Guide - Detailed explanation of the PROMATE® II programming features, set up and usage - DS30082

All PROMATE® II documentation is to be found on the PROMATE® II product page at http://www.microchip.com/promateii

TIP! - MPLAB® IDE, if installed, has release specific information for all of these tools. Look at [DRIVE]:\<INSTALL PATH>\Microchip\MPLAB IDE\Readmes. The "Device Support.html" file lists the support status of each microcontroller for all of the currently supported tools!

Mature Programming Tools

When using MPLAB® IDE, reference will also be made to a programmer named PICkit™ 1. The PICkit™ 1 was the forerunner to the present PICkit™ 3 (and PICkit™ 2) tool but only offered programming capability and was targeted to support a few PIC10, PIC12 and PIC16 flash microcontrollers. The tool was delivered with a PIC12F675 and a package of tutorials to allow the user to make their first steps with assembly programming and show how to configure and use some of the key peripheral modules. The visual programming interface was the MPLAB® IDE. Essentially developed to provide a low-cost entry point to microcontroller development, this tool is no longer actively developed . More information on the tool and links to the documentation are to be found at http://www.microchip.com/pickit1

Flash program memory programming documentation

The last group of generic documentation we will discuss here is that describing the process of programming the flash memory of the microcontroller. Essentially there are three purposes that are covered in the documentation regarding how to program the flash, namely:

• The programming procedure for production programmers
• How to prepare the interface for in-circuit programming for production
• How to modify the contents of the flash in a running application

The three purposes and the associated documentation are discussed in more detail below.

Programming procedure for production programmers

If you intend to support Microchip's microcontrollers with the programming tools you manufacture, or you intend to manufacture or implement your own programming tools for your production line, you will need to examine the programming protocol documentation to understand how the flash memory is accessed and instructions are programmed into the flash. There are four potential methods, all serial based, for programming the flash memory of a PIC microcontroller.

• ICSP™ - in-circuit serial programming is the standard interface for flash programming. Using two of the controllers GPIO pins (one as a clock and another as a bi-directional data line) as a communications interface the desired instructions are transferred to the controller and programmed into the flash using a specially defined protocol. The protocol is specific to one family of microcontrollers due to the different memory widths of the flash of each family. The programming mode is entered by holding the clock and data lines low (typically named PGC and PGD) and applying a high voltage on the MCLR/V_PP pin, with a "high voltage" being somewhere in the range 8.0V to 13.5V for 8-bit products and the supply voltage (V_DD) for 16 and 32-bit products. The exact voltage is specified in the "Programming Specification" documentation. Once in programming mode the microcontroller's flash memory can be written and read until programming mode is left by removing the high-voltage from the MCLR/V_PP pins upon completion of the last programming command. ICSP™ is available on all flash-based PICs.
• Low-Voltage ICSP™ - the low-voltage in-circuit programming uses the same communications interface and protocol, but does not require the high-voltage signal on the MCLR/V_PP pin which can be difficult to accommodate in a design. Instead the clock and data pins must be held low while a third pin, PGM, is held high after which the MCLR/V_PP pin must be pulled up to the standard operating voltage of the microcontroller. Not all microcontrollers support low-voltage ICSP™ and, if supported, the low-voltage programming bit LVP in the controllers configuration bits register must be set to '1'. If this bit is cleared to '0', the normal high-voltage ICSP™ method must be used to set this bit back to '1' again. Low-Voltage ICSP™ is available on most 8-bit products.
• Enhanced ICSP™ - enhanced ICSP™ uses the same programming interface in conjunction with a programming executive (PE), a small piece of firmware, to simplify the programming process. The programming executive takes over the low-level programming procedure, allowing the programmer tool to concentrate on executing higher-level programming commands such as 'read memory' and 'blank check' which would otherwise have to be undertaken by the programming tool and possibly a host PC system. This results in faster programming times and less overhead in the programming procedure from the side of the programming tool. The PE is executed from flash in the 16-bit controllers and may or may not already be available when entering programming mode. The PE for 32-bit controllers must be downloaded into RAM after entering programming mode. Enhanced ICSP™ is available on the dsPIC30, dsPIC33, PIC24 and PIC32 families.
• Enhanced JTAG - the PIC32 family is the first and only microcontroller family from Microchip which currently supports flash programming via the JTAG interface. The JTAG interface programming protocol is more or less the same as for ICSP™ on the PIC32 as the communication in both cases passes through the JTAG interface's TAP controller. Enhanced JTAG can also make use of a programming executive, in the same way as the enhanced ICSP™ previously described, if desired.

The documentation for flash programming is, unfortunately, not always the same for an entire family of microcontrollers but is instead typically common to a small collection of controllers from a family. To provide an idea of what to expect, a few example documents are listed below.

• From the baseline family: Memory Programming Specification for PIC10F200/202/204/206 - DS41228
• From the midrange family: PIC16F/LF182X/PIC12F/LF1822 Memory Programming Specification - DS41390
• From the high-performance family: Flash Microcontroller Programming Specification for PIC18FX220/X320 - DS39592
• From the 16-bit MCU family: PIC24FJXXXGA0XX Flash Programming Specification - DS39768
• From the 16-bit DSC family: dsPIC30F Flash Programming Specification - DS70102
• From the 32-bit family: PIC32MX Flash Programming Specification - DS61145

Interface for in-circuit programming for production programming

The ICSP™ interface is very simple to implement, requiring only two connections to the PGC and PGD pins of the microcontroller, and a connection to the MCLR/V_PP pin. In addition, the programming tools or debuggers also need to connect to GND and V_DD to complete the electrical connection and detect the power supply voltage and availability prior to programming. Despite this apparent simplicity, the reality of trying to program a microcontroller in an electrical circuit is slightly more complicated as the PGC and PGD pins may also be being used as GPIO pins in the circuit, and the MCLR/V_PP may be connected to other circuitry in the system. In order to ensure successful programming (and this applies to debugging as well) it is necessary to ensure that basic design principles are followed. These principles include:

• No capacitors should be connected to MCLR/V_PP, PGC or PGD as this will affect the fast signal transitions used in the ICSP™ communications protocol
• No pull-up resistors on PGC or PGD as these will function as a voltage divider in conjuction with the internal pull-down resistors in most tools
• No diodes in the PGC or PGD connections between the microcontroller and the programming tool due to the bi-directional communications interface
• Many documents recommend a schottky-diode between MCLR/V_PP and the remaining circuitry to protect the main circuit from the high voltage applied to this pin to enter programming mode

Every programmer and debugger document provides recommended guidelines in its 'User's Guide' for the best way of implementing the ICSP™ interface in conjunction with that tool, and it is recommended to take the time to carefully read this before finalising the hardware design of the planned application. The 'Quick Start Poster' for the tool also typically covers this topic. In addition, searching for the term 'ICSP' in the datasheet of your chosen microcontroller will offer further recommendations and advice. Finally there are some other documents available on the website which directly tackle the programming interface, such as:

• TB016 - How to Implement ICSP™ Using PIC16F8X FLASH MCUs - DS91016

Modifying the contents of the flash in a running application

All of the PIC microcontroller families, with the exception of the baseline products, have the ability to modify the content of their own flash program memory during the run-time of the application. The manner in which this is implemented, how it is documented and how it is named is dependent on the microcontroller family. The following provides guidance on where to look and in which documentation to find out more information:

• Mid-range and Enhanced mid-range devices - self-writing of the program flash is achieved by performing writes through the EEPROM registers to erase and re-write desired locations. It is important to note that the controller cannot execute its own code as it writes its own program memory, and program execution will be stopped for a time in the order of some milliseconds. Additionally take careful note of the reference assembler code in the datasheet and a very specific sequence of code is needed to enable the erase and write process. Refer to the device's datasheet and search for a chapter which is typically named "DATA EEPROM AND FLASH PROGRAM MEMORY CONTROL".
• High-performance devices - these devices use a process known as "Table Reads and Table Writes" which uses a combination of special registers and special "table write" assembly instruction to modify the content of the program flash. Like the mid-range family, the controller must wait for the write process to complete before it can continue to execute code which can take several milliseconds to complete. The code required to write memory also requires a very specific sequence and is provided in the datasheet as assembly code. Refer to the device's datasheet and search for a chapter which is typically named "FLASH PROGRAM MEMORY" and read further for a section called "Writing to Flash Program Memory" or similar.
• 16-bit MCU and DSC devices - although these devices use the same "Table Reads and Table Writes" process used by the high-performance 8-bit family, the self-writing capability is named Run-Time Self programming or RTSP. Like the other families, the controller must wait for the write process to complete before it can continue to execute code which can take several milliseconds to complete. The required assembly code sequence for self-programming of the flash is also very important to follow with reference code being provided in the datasheet. Refer to the device's datasheet and search for a section which is typically named "RTSP Operation" which is typically found in the "Flash Program Memory" chapter.
• 32-bit devices - like their 16-bit cousins, the self-writing capability of the 32-bit family is also named Run-Time Self programming or RTSP. Like the other families, the controller must wait for the write process to complete before it can continue to execute code which can take several milliseconds to complete. Refer to the device's datasheet and search for a section which is typically named "RTSP Operation" or search for the same term in the PIC32MX Family Reference Manual.