A Guide To PIC Microcontroller Documentation/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 emebedded 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.

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®^[1], 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^[2].

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^[3]).

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.

References

1. ↑ http://www.microchip.com/mplab
2. ↑ http://search.microchip.com/searchapp/searchhome.aspx?id=2&q=DS51281
3. ↑ http://search.microchip.com/searchapp/searchhome.aspx?id=2&q=DS51519