A Guide To PIC Microcontroller Documentation/Print version

A Guide to PIC Microcontroller Documentation

A PIC microcontroller.

Datasheets for semiconductor products can be baffling even for the most experienced engineers and programmers, but those written for microcontroller or digital signal processing products are even more so. One of the challenges of writing a datasheet for such products is that, due to their programmable nature, diversity and flexibility, it is difficult to successfully separate out the raw data about the product and its peripherals from programming them and ultimately developing functioning applications based upon them.

Even those with several years experience on one family of products from one silicon manufacturer may have difficulty finding the information they are accustomed to in the documentation of an alternative silicon supplier. This is due to each manufacturer writing their documents in differing ways and even using varying terminology or acronyms for the same terms.

This guide aims to explain what type of information is split over which documents for the Microchip PIC family of microcontrollers and digital signal controllers from Microchip Technology which should help those making their first tentative steps with this broad range of controller products.

Who is this written for?

This guide is written primarily for professional embedded developers who are moving to the Microchip range of controller products for the first time and need guidance on where to find the information they need to make informed decisions on the products' capabilities or how to program and use them.

It is also ideal for those in higher education (both learning and teaching) to gain an insight into how technical information on complex silicon products is written and which details are to be found where. For those who take a personal interest in these products, but do not necessarily work in the embedded system profession, enlightenment may also be found as to why certain information is documented as it is and where.

How this book is constructed

This book is split into three sections; the first is recommended reading for all those reading this book for the first time and ensures that basic knowledge required to understand the rest of the book is clarified; the second section examines the documentation available for the different products on a controller family and sub-family basis, ideal for those making a start with a particular Microchip PIC device; the third and final section is a terms-based guide to documentation allowing those with previous knowledge (either with these products or those from an alternative supplier) to get quickly to the information they need, based upon the knowledge they already have.

Table of Contents

• Section 1 - Introduction to Microchip PIC Microcontroller and DSC products
  • Methodology behind Microchip PIC Microcontroller and DSC documentation
  • Linking documentation to controller family
  • Controller and Development Documentation Structure
  • Development Tool and Manufacturing Documentation Structure
• Section 2 - Processor-family based guide to documentation
• Section 3 - Term-based guide to documentation

Recommended prior knowledge

This book assumes the reader has a grounding in electronics, microcontroller architecture and programming, embedded systems or a combination of all three. Terminology common to these areas will be used without further definition or explanation.

Appendices

Authors and contributors

Notes for contributors

Translations

Glossary

A Guide to PIC Microcontroller Documentation

Methodology behind PIC® controller documentation

Microcontrollers and digital signal processors (DSPs) are challenging products to document. On the one hand, the semiconductor vendor has to describe the functionality of the device's processing core, the functionality and possible settings of peripherals and the electrical and packaging specifications of the device. This description needs to concentrate on the raw functionality of the device's circuitry and the registers which they form. For example, a UART (Universal Asynchronous Receiver Transmitter) peripheral's functionality, as described in a datasheet, focuses upon, among other things, setting up the related transmit and receive pins of the device for use as a serial interface, how to calculate the required baudrate settings and how to enable parity support.

On the other hand, raw details on functionality and setup alone cannot inform a developer how to use that peripheral, processor or other feature in an actual application. Using our UART example again we know that a UART can be used in a variety of serial interfacing standards such as RS-232 and RS-485 amongst others. In addition that standard may have standardized software layer with which it is commonly used (for example ANSI escape sequences used with VT100), and a common circuit layout external to the controller to implement the required signalling (for example a MAX-232 family transceiver used with RS-232).

A further challenge documenting controller products is due to their infinite flexibility, as programmable products, and the fact that the software can be written in a variety of different programming languages using a broad range of software tools from different vendors of which some, or perhaps none, come from the silicon vendor themselves.

Lastly there is the issue of the software programs and hardware tools used for creating and debugging the firmware for the controller and the programming tools used for small production runs or mass-production.

As a result, datasheets alone typically contain around 100 pages, often running to several hundred pages, and in the interest of keeping the size of the datasheet manageable, much common and implementation or application specific data is located in various other documents with names such as "Family Reference Manual", "Application Note" or "Programming Specification".

A Guide To PIC Microcontroller Documentation <-- Return to start of book

Next Section --> Linking Documentation To Controller Family

Linking documentation to controller family

Since the inception of Microchip Technology in 1989 and the first PIC® microcontrollers, the PIC16C5X family, a fairly consistent pattern of documentation has emerged which has been retained as the 8-bit families grew and newer 16-bit and 32-bit families have been added.

The first step to getting the information you are seeking is to understand which family of product you intend to use. The 8-bit product family is especially confusing in this area since products with the same prefix, i.e. PIC12 or PIC16, are not necessarily all based upon the same underlying processor architecture.

8-bit families

The 8-bit family of RISC Havard-architecture microcontrollers are based upon four different processor architectures with a common core set of assembler instructions which are upwards compatible across the sub-families. In addition many devices share common peripherals, even across sub-families, providing an easy migration path for developers. The four sub-families are officially named:

• Base-Line - devices based upon a processor core using a 12-bit instruction set. Microcontrollers with the prefix PIC10, PIC12 or PIC16 could be base-line products.
• Mid-Range - devices based upon a processor core using a 14-bit instruction set. Microcontrollers with the prefix PIC12 or PIC16 could be mid-range products. The rfPIC12 devices (with integrated radio transmitter) also belong to this family.
• Enhanced Mid-Range - devices based upon a processor core using a 14-bit instruction set with extended instruction set, larger memory addressing and other improvements compared to mid-range products. Microcontrollers with the prefix PIC12F1 and PIC16F1 are extended mid-range products.
• High-End - devices based upon a processing core using a 16-bit instruction set, some of which may also have a high-level programming language optimised extended instruction set and data-memory addressing. Microcontrollers with the prefix PIC18 will be a high-end product.

Documentation Search Challenges - When searching for documentation, nothing is more important than knowing which search term to use. Microchip has not been very consistent over the years with the naming of the underlying processor cores of their products. When searching the web or reading printed or PDF documentation you may find the following terms used: For Base-Line: Baseline For Mid-Range: Midrange For Enhanced Mid-Range: Enhanced midrange For High-End: High-Performance, PIC18 Architecture, Enhanced Device

First Steps for Developers - With some microcontrollers using one of two different processing cores (PIC12 and PIC16) it is important to know which underlying processor architecture is being used as this affects which further documentation you need to download to support your development. When you have selected a microcontroller, locate and download its datasheet. It is unlikely that the underlying processor core will be named in the document, but by searching for the chapter on "Memory Organisation - Program Memory Organisation" and finding out how many bits per word of program memory there are you can easily tell to which sub-family an 8-bit microcontroller belongs. Sometimes the number of bits per instruction word will also be listed on the third page as part of the "CPU Features".

16-bit families

The 16-bit family of RISC Havard-architecture products are split into two groups; MCU microcontrollers and DSC digital signal controllers. DSC is used as the acronym for devices featuring a digital signal processing unit (DSP) in the controller's core, with DSC being preferred over the more traditional DSP to highlight the devices suitability for embedded control applications and the demands they have compared to DSP products which a used in pure signal processing applications. The sub-families can be identified by their prefixes, namely:

• dsPIC30/dsPIC33 - 16-bit DSC with 24-bit instruction set and dual 16-bit data buses to support the MAC (multiply and accumulate) instructions.
• PIC24F/PIC24H - 16-bit MCU with 24-bit instruction set; featuring the same processor architecture as the dsPICs minus the DSP module and associated instructions. Multiplier is simplified supporting single cycle 17-bit x 17-bit multiplication. Single 16-bit data bus.

These controllers feature peripheral modules which are in many cases common to both sub-families and, in some cases, common to the 8-bit PIC18 controllers and the PIC32 products. Some dsPICs feature high-frequency PWM modules, making them suitable for the control of BLDC motors, AC Induction motors and integration in digital SMPS. Certain PIC24F devices feature a graphics controller making them suitable for the direct control of monochrome and colour STN and colour TFT LCD displays. Other features include USB (peripheral and host), CAN, and serial interfaces such as SPI, I²C and USART making them suitable for a wide range of consumer and industrial applications.

32-bit families

The 32-bit family of microcontrollers feature the MIPS® Technologies M4K® processor core, a high-performance, low-power RISC core, and are identified by the prefix PIC32. There are currently four sub-families:

• PIC32MX3 - General purpose 32-bit microcontroller featuring common embedded MCU peripherals
• PIC32MX4 - General purpose 32-bit microcontroller featuring common embedded MCU peripherals and USB 2.0 OTG interface, suitable for use as On-The-Go, USB peripheral or USB host
• PIC32MX5 - General purpose 32-bit microcontroller featuring common embedded MCU peripherals, USB 2.0 OTG interface (as the MX3) and CAN
• PIC32MX6 - General purpose 32-bit microcontroller featuring common embedded MCU peripherals, USB 2.0 OTG interface (as the MX3) and 10/100 Ethernet MAC
• PIC32MX7 - General purpose 32-bit microcontroller featuring common embedded MCU peripherals, USB 2.0 OTG interface (as the MX3), 10/100 Ethernet MAC and dual CAN interfaces

The general purpose peripherals on these devices are the same as those featured in the 16-bit family, and the devices are additionally pin-to-pin compatible with many of their 16-bit MCU family counterparts.

Mature families

While searching for documentation, you may find documentation on the following controller products which are no longer recommended for new designs:

• PIC14000 - a RISC Harvard architecture CPU based "Mixed Signal Controller" with a 14-bit instruction set. A PIC16F883 is recommend as an alternative to this product.
• PIC17 - a RISC modified Harvard architecture CPU based microcontroller family with a 16-bit instruction set. PIC18 devices are recommended as an alternative to PIC17 products.

Introduction to PIC microcontroller and DSC products <-- Previous Section

Next Section --> Controller and Development Tool Documentation Structure

Controller and Development Tool Documentation structure

Having identified the processor architecture used by the chosen PIC product, it is time to start acquiring (typically downloading) the required documentation. Documentation in this sense is not restricted to the controller device you intend to use, rather it encompasses all documentation needed to develop code, debug code, program the device's memory and layout and design related hardware which are all elements of implementing an embedded product based upon a specific controller. The main documentation groups can thus be defined 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 first three points will be examined in more detail.

Depending on how development activities are split, a single developer may be responsible for all stages of the design process from conception through to manufacture, whilst others may only be responsible for a small part of the design process. In either case, it is highly recommended to gather all the relevant documentation and at least peruse those documents which are not so pertinent to one's own role in the design flow in case something from an earlier or later stage in the design process has an influence on the aspect of development for which one is responsible.

For example, to discover during the first production run that a controller pin needed for programming is used by another feature which could have been easily connected to another, perhaps unused, pin will typically require an expensive hardware redesign and delays the products launch.

TIP! - Preparation is everything, and well thought-through decisions, and even corrections, made early on in the design cycle save exponential sums of money, as well as time, compared to resolving them later on!

Microcontroller and DSC Documentation

Documentation for microcontroller and DSC products can be broken down into three core document types:

• Datasheet - the datasheet documents how a specific controller device, or a group of devices with the same subset of features, functions. This document typically includes, as a minimum, descriptions of the processing core, memory, peripherals, electrical characteristics, timing characteristics, packaging types and general development information.
• Errata - many devices also have errata which describe situations where the chosen device, or group of devices, do not function precisely as described in the datasheet. Where possible a workaround for the issue is also offered. Often such issues are restricted to a single peripheral, often in a specific mode of operation or under certain usage conditions.
• Family Reference Manual - the Family Reference Manual, when available, can be considered the inverse of the datasheet. Where the datasheet contains device specific information, this document provides generic information at the sub-family level of the internal workings of the controllers and their peripherals. This document often contains application relevant code examples and a detailed description of the processor architecture which, if included in every related datasheet, would unnecessarily expand the size of the datasheet. Naturally, care must be taken when using this document to ensure that the same peripheral (or version of that peripheral) and the required pins are actually available on the device being used by referring back to the datasheet. Due to the volume of information contained within its pages, individual chapters of this document may be available for download as well as the entire document.

Other documents that can be downloaded on an "as needs" basis include:

• Programmer's Reference Manual - for the 16-bit devices there is an additional document called a "Programmer's Reference Manual". Within its pages are a detailed description of the 16-bit architecture as well as information on the DSP side of the dsPIC products. The instruction set is also covered in some detail.
• Application Notes - describe how to implement a complete application and generally include a schematic layout and functional source code in a ZIP file.
• Technical Briefs - similar in content to Application Notes but shorter, hence the name "brief". May or may not include source code for the content discussed. Sometimes these documents discuss research oriented topics, such as "PLL Jitter and its Effect on ECAN Protocol".
• Code Examples - Quite simply, source code for to demonstrate a functionality (e.g. JPEG entropy coding) or application. A ZIP file containing an MPLAB project, source code, and documentation in a "readme" text file.
• User Guides - if using a Microchip hardware development board, the User Guide contains information on its use and its schematics. User Guides are not restricted to documenting development boards.
• Tip&Tricks - available as separate documents, or as a compendium of all the documents in a single book. These helpful guides are packed full of ideas on how to get the most out of microcontrollers and their peripherals based upon the vast experience of Microchip's engineers with their customers. Something to refer to in a coffee-break for inspiration when all else has failed!

Not strictly documentation, but definitely something helpful during the design and manufacturing process, are the following electronic files which are sometimes available:

• BSDL Files - used for implementing boundary scan during manufacturing.
• CAD/CAE Footprints and Schematic Symbols - provides the symbols and footprints needed for PCB layout for around ten of the most popular CAD/CAE design tools.

Programming language documentation

Developing software for PIC controllers can be undertaken using one of two programming languages using the tools available from Microchip; assembler or C. These and other programming languages are also offered from third-parties or supported through open-source projects. The software package supporting a specific programming language is typically called a "toolsuite" or "tool-chain", depending on the document being read, as it contains not one but a multitude of software programs which can convert source code into binary code and the other files typically used during software development on the target controller.

The tools and their documentation are family specific and are discussed in the relevant family specific chapters.

Integrated Development Environment (IDE) documentation

Although it is possible to develop software for applications without resorting to an IDE, medium to large size projects quickly benefit from the structure and features an IDE provides, allowing project based settings to be set using a visual environment and binary code to be generated without resorting to command-line calls or writing batch or make files. On the downside, obviously there are a lot of settings to be tackled to create the first project and, as with any new software, it is difficult to know in the first instance where to "click", what to select, and what to enter in all the boxes.

Microchip offers their own IDE, called MPLAB®, which can be used for code development on all of their controller products and be used with all of their current development tools. In order to get over the initial hurdle, the first documentation point is the "MPLAB® IDE Quick Start Guide", document DS51281.

Once the first few test projects have been tackled, the "MPLAB® IDE User's Guide" should be referred to for further in depth information on features and functions in the IDE (document DS51519).

With MPLAB® itself there are also numerous compiler HTML help files containing, amongst other things, tutorials. Like all help files the key is to knowing which terms to search for, which itself is sometimes an art in its own right.

Since MPLAB® is controller product independent the documentation of this software is not be discussed in the device family specific chapters.

TIP! - You can search for the file names noted here (e.g. DS51281) either on the Microchip website or on Google. However note that the filenames will also include a postfix letter denoting the revision of the document which starts with the letter "A" when you find them (e.g. DS51281F).

Linking Documentation To Controller Family <-- Previous Section

Next Section --> Development Tools and Manufacturing Documentation Structure

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.

Detailed analysis of controller family documentation

In this section we will be taking an in depth look at the main documentation for one controller out of each PIC microcontroller family. In each case the key documents will be listed and then the datasheet will be analysed chapter by chapter to highlight the information that is provided, and how related information can be found in the cases where the documentation is rather sparse.

In each case we will select a device that is the largest in its class in terms of performance, memory and number of peripherals. All other devices in that family will contain a sub-section of the information contained in the analysed device. There is a lot of similarity between families, and therefore there will be lots of repetition between chapters here, but since each engineer only focusses on one family or device at one time this method of documenting the datasheets here should prove to be most beneficial to the reader.

Further reading

• http://microchip.wikidot.com/
• The PIClist is a mailing list of people discussing Microchip PICmicros and related devices and the things people do with them. There's a huge amount of useful code in the archives and wiki-like library.
• The Electronics Engineering stackexchange often discusses PICmicros.

A PIC microcontroller.

Datasheets for semiconductor products can be baffling even for the most experienced engineers and programmers, but those written for microcontroller or digital signal processing products are even more so. One of the challenges of writing a datasheet for such products is that, due to their programmable nature, diversity and flexibility, it is difficult to successfully separate out the raw data about the product and its peripherals from programming them and ultimately developing functioning applications based upon them.

Even those with several years experience on one family of products from one silicon manufacturer may have difficulty finding the information they are accustomed to in the documentation of an alternative silicon supplier. This is due to each manufacturer writing their documents in differing ways and even using varying terminology or acronyms for the same terms.

This guide aims to explain what type of information is split over which documents for the Microchip PIC family of microcontrollers and digital signal controllers from Microchip Technology which should help those making their first tentative steps with this broad range of controller products.

Who is this written for?

This guide is written primarily for professional embedded developers who are moving to the Microchip range of controller products for the first time and need guidance on where to find the information they need to make informed decisions on the products' capabilities or how to program and use them.

It is also ideal for those in higher education (both learning and teaching) to gain an insight into how technical information on complex silicon products is written and which details are to be found where. For those who take a personal interest in these products, but do not necessarily work in the embedded system profession, enlightenment may also be found as to why certain information is documented as it is and where.

How this book is constructed

This book is split into three sections; the first is recommended reading for all those reading this book for the first time and ensures that basic knowledge required to understand the rest of the book is clarified; the second section examines the documentation available for the different products on a controller family and sub-family basis, ideal for those making a start with a particular Microchip PIC device; the third and final section is a terms-based guide to documentation allowing those with previous knowledge (either with these products or those from an alternative supplier) to get quickly to the information they need, based upon the knowledge they already have.

Table of Contents

• Section 1 - Introduction to Microchip PIC Microcontroller and DSC products
  • Methodology behind Microchip PIC Microcontroller and DSC documentation
  • Linking documentation to controller family
  • Controller and Development Documentation Structure
  • Development Tool and Manufacturing Documentation Structure
• Section 2 - Processor-family based guide to documentation
• Section 3 - Term-based guide to documentation

Recommended prior knowledge

This book assumes the reader has a grounding in electronics, microcontroller architecture and programming, embedded systems or a combination of all three. Terminology common to these areas will be used without further definition or explanation.

Appendices

Authors and contributors

Notes for contributors

Translations

Glossary

Authors

• Codinghead - Stuart Cording, User Codinghead's Page

D

• DSP - Digital Signal Processor - processor designed to efficiently process discrete signal data (e.g. audio, video). Key processor instruction on a DSP is the MAC instruction (multiply and accumulate) which allows a single piece of data to be multiplied by a single coefficient value and added to the value currently in the processors accumulator, all in a single processing cycle.
• DSC - Digital Signal Controller - acronym used by Microchip Technology to define their dsPIC family of products which contain a microprocessing core and a DSP. The alternative definition is used to highlight the products embedded control properties (fixed latency times for jumps into interrupt routines, fixed instruction processing time) regardless of which instruction the processor is currently processing, which is typically not the case for pure DSP architectures.

W

• Workaround - typically a software solution to a hardware problem in a controller product. Usually involves reordering code to avoid a hardware problem, or changing a setting under certain situations.