MPLAB® Harmony v2 Peripheral Library (PLIB) Overview

Peripheral Libraries

A Peripheral Library (PLIB) is a simple access library that provides a consistent but very low-level interface to a peripheral on the microcontroller. PLIBs hide register details, making it easier to write drivers that support multiple microcontroller families. They are not normally used by applications to directly interact with peripherals as they provide little abstraction and because they require the caller to manage the detailed operation of a peripheral, including preventing conflicting requests from other modules.

Because of the lack of conflict protection in a PLIB, only one module in a system should directly access the PLIB for a peripheral. Therefore, PLIBs are primarily used to implement device drivers (and some system services) to make them portable.

MPLAB® Harmony Peripheral Libraries (PLIBs) model the hardware peripheral modules available on Microchip microcontrollers by breaking each peripheral down into a set of individual features. For example, a simplified Universal Asynchronous Receiver/Transmitter (UART) peripheral module may have three features: transmitter, receiver, and baud rate.

The baud rate feature may have two operations that can be performed. One operation might be a "set" function to set the current baud rate at which the UART will send and receive data and the other might be a "get" operation to find out the baud rate at which the UART is currently transmitting and receiving. Here are examples of Harmony C language functions that perform these operations.

void   PLIB_USART_BaudRateSet( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate );

uint32_t   PLIB_USART_BaudRateGet( USART_MODULE_ID index, int32_t clockFrequency );

Notice that each function accepts an “index” parameter as well as data parameters relevant to the operation itself, such as the input clock frequency and desired baud rate. The “index” parameter allows one set of PLIB functions to support any number of instances of the peripheral on a given microcontroller. Thus, each peripheral library exposes all of the features available on all instances of a given type of peripheral.

The function signature (name, parameters, and return value) for the operations supported by that feature will be the same on all microcontrollers even if the implementations of those functions are different from one microcontroller to another. These are known as "implementation variants." As illustrated in the following diagram, a PLIB implementation is made up of the complete set of default and variant implementations of the operations of every feature supported by a specific type of peripheral on a specific microcontroller. Using this method, MPLAB Harmony Peripheral Libraries provide consistent C-language functional interfaces to access the peripherals available on all supported microcontrollers.

However, if a feature is not supported on all instances of the peripheral on all supported microcontrollers, the peripheral library communicates this to the developer in one of two ways. If a feature is not supported by any instance of the peripheral on a given microcontroller, the primitive functions related to that feature will also be unsupported and they will cause build warnings indicating this if they are called. If a feature is supported on at least one, but not on all of the available instances of the peripheral on the microcontroller in use, then the functions will be supported, but they will provide a run-time error to facilitate debugging. Which features are supported on each instance of each microcontroller is documented in the help material for each peripheral library.

Fundamentally, peripheral libraries are peripheral access libraries. PLIB function calls do not block or call anything outside of the PLIB itself (with the exception of some removable debugging support). A PLIB function does not maintain any state data (outside of the data stored in hardware registers) as it may be called from within the main line of execution, from within an RTOS thread, or from within an ISR. Also, PLIB functions are normally generated as PLIB_INLINE, not as actual function calls (although optimized, prebuilt PLIB libraries are provided to support those times when the compiler does not generate the function PLIB_INLINE). A PLIB simply provides the ability to directly access and manipulate the features of a given peripheral using primitive operations. It is the responsibility of the calling module (usually the device driver) to store and appropriately protect any state data necessary to keep the peripheral running.

So, while an application (or any other layer) may directly access the PLIB for any particular peripheral in the system, if it does, it must be the only module in the system that does this and it then becomes responsible for the correct operation. That is why PLIBs are not normally the recommended way to access peripherals. It is usually better to access a peripheral through a driver or system service that manages the state machine of the peripheral and protects the peripheral so that accesses to it from multiple clients will not interfere with the correct operation of the peripheral.

To get more details on specific Peripheral Libraries, visit the "Controlling Common Peripherals Using Harmony v2" page.

© 2024 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.